@query-doctor/core 0.10.2 → 0.10.4

package/dist/action-plan/aggregate-index-recommendations.cjs

@@ -0,0 +1,52 @@
+"use client";
+//#region src/action-plan/aggregate-index-recommendations.ts
+/**
+* Collapse a set of analyzed queries into one entry per unique index
+* definition, scored by the percentage cost reduction of the queries it helps.
+*
+* This is the shared primitive behind the live-query and CI-run recommendation
+* views. Ranking here is the legacy "most queries, then biggest single
+* percentage" order; the absolute-cost ranking the dashboard action plan needs
+* lives in {@link buildActionPlan}.
+*/
+function aggregateIndexRecommendations(queries) {
+	const indexMap = /* @__PURE__ */ new Map();
+	for (const query of queries) {
+		if (query.optimization.state !== "improvements_available") continue;
+		const { indexRecommendations, costReductionPercentage } = query.optimization;
+		if (!indexRecommendations || costReductionPercentage === void 0) continue;
+		for (const indexRec of indexRecommendations) {
+			const key = indexRec.definition;
+			const existing = indexMap.get(key);
+			if (existing) {
+				existing.queryHashes.push(query.hash);
+				existing.costReductions.push(costReductionPercentage);
+			} else indexMap.set(key, {
+				index: indexRec,
+				queryHashes: [query.hash],
+				costReductions: [costReductionPercentage]
+			});
+		}
+	}
+	const aggregated = [];
+	for (const data of indexMap.values()) {
+		const averageCostReduction = data.costReductions.reduce((sum, val) => sum + val, 0) / data.costReductions.length;
+		const bestCostReduction = Math.max(...data.costReductions);
+		aggregated.push({
+			index: data.index,
+			affectedQueryCount: data.queryHashes.length,
+			averageCostReduction,
+			bestCostReduction,
+			affectedQueryHashes: data.queryHashes
+		});
+	}
+	aggregated.sort((a, b) => {
+		if (a.affectedQueryCount !== b.affectedQueryCount) return b.affectedQueryCount - a.affectedQueryCount;
+		return b.bestCostReduction - a.bestCostReduction;
+	});
+	return aggregated;
+}
+//#endregion
+exports.aggregateIndexRecommendations = aggregateIndexRecommendations;
+
+//# sourceMappingURL=aggregate-index-recommendations.cjs.map

package/dist/action-plan/aggregate-index-recommendations.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-index-recommendations.cjs","names":[],"sources":["../../src/action-plan/aggregate-index-recommendations.ts"],"sourcesContent":["import type { IndexRecommendation } from \"../query.js\";\nimport type { AggregatedIndexRecommendation } from \"./index-coverage.js\";\n\n/**\n * Minimal per-query shape the action-plan consolidation reads. Structurally\n * compatible with both the live-query optimizer state and the CI run query\n * result, so callers on either side can pass their records directly without an\n * adapter. Only the `improvements_available` state carries index actions; every\n * other state is ignored.\n */\nexport interface ActionPlanQuery {\n  hash: string;\n  optimization: {\n    state: string;\n    cost?: number;\n    optimizedCost?: number;\n    costReductionPercentage?: number;\n    indexRecommendations?: IndexRecommendation[];\n  };\n}\n\n/**\n * Collapse a set of analyzed queries into one entry per unique index\n * definition, scored by the percentage cost reduction of the queries it helps.\n *\n * This is the shared primitive behind the live-query and CI-run recommendation\n * views. Ranking here is the legacy \"most queries, then biggest single\n * percentage\" order; the absolute-cost ranking the dashboard action plan needs\n * lives in {@link buildActionPlan}.\n */\nexport function aggregateIndexRecommendations(\n  queries: readonly ActionPlanQuery[],\n): AggregatedIndexRecommendation[] {\n  const indexMap = new Map<\n    string,\n    {\n      index: IndexRecommendation;\n      queryHashes: string[];\n      costReductions: number[];\n    }\n  >();\n\n  for (const query of queries) {\n    if (query.optimization.state !== \"improvements_available\") continue;\n\n    const { indexRecommendations, costReductionPercentage } =\n      query.optimization;\n    if (!indexRecommendations || costReductionPercentage === undefined)\n      continue;\n\n    for (const indexRec of indexRecommendations) {\n      const key = indexRec.definition;\n      const existing = indexMap.get(key);\n\n      if (existing) {\n        existing.queryHashes.push(query.hash);\n        existing.costReductions.push(costReductionPercentage);\n      } else {\n        indexMap.set(key, {\n          index: indexRec,\n          queryHashes: [query.hash],\n          costReductions: [costReductionPercentage],\n        });\n      }\n    }\n  }\n\n  const aggregated: AggregatedIndexRecommendation[] = [];\n\n  for (const data of indexMap.values()) {\n    const averageCostReduction =\n      data.costReductions.reduce((sum, val) => sum + val, 0) /\n      data.costReductions.length;\n    const bestCostReduction = Math.max(...data.costReductions);\n\n    aggregated.push({\n      index: data.index,\n      affectedQueryCount: data.queryHashes.length,\n      averageCostReduction,\n      bestCostReduction,\n      affectedQueryHashes: data.queryHashes,\n    });\n  }\n\n  // Most affected queries first, breaking ties by the biggest single reduction.\n  aggregated.sort((a, b) => {\n    if (a.affectedQueryCount !== b.affectedQueryCount) {\n      return b.affectedQueryCount - a.affectedQueryCount;\n    }\n    return b.bestCostReduction - a.bestCostReduction;\n  });\n\n  return aggregated;\n}\n"],"mappings":";;;;;;;;;;;AA8BA,SAAgB,8BACd,SACiC;CACjC,MAAM,2BAAW,IAAI,KAOlB;AAEH,MAAK,MAAM,SAAS,SAAS;AAC3B,MAAI,MAAM,aAAa,UAAU,yBAA0B;EAE3D,MAAM,EAAE,sBAAsB,4BAC5B,MAAM;AACR,MAAI,CAAC,wBAAwB,4BAA4B,KAAA,EACvD;AAEF,OAAK,MAAM,YAAY,sBAAsB;GAC3C,MAAM,MAAM,SAAS;GACrB,MAAM,WAAW,SAAS,IAAI,IAAI;AAElC,OAAI,UAAU;AACZ,aAAS,YAAY,KAAK,MAAM,KAAK;AACrC,aAAS,eAAe,KAAK,wBAAwB;SAErD,UAAS,IAAI,KAAK;IAChB,OAAO;IACP,aAAa,CAAC,MAAM,KAAK;IACzB,gBAAgB,CAAC,wBAAwB;IAC1C,CAAC;;;CAKR,MAAM,aAA8C,EAAE;AAEtD,MAAK,MAAM,QAAQ,SAAS,QAAQ,EAAE;EACpC,MAAM,uBACJ,KAAK,eAAe,QAAQ,KAAK,QAAQ,MAAM,KAAK,EAAE,GACtD,KAAK,eAAe;EACtB,MAAM,oBAAoB,KAAK,IAAI,GAAG,KAAK,eAAe;AAE1D,aAAW,KAAK;GACd,OAAO,KAAK;GACZ,oBAAoB,KAAK,YAAY;GACrC;GACA;GACA,qBAAqB,KAAK;GAC3B,CAAC;;AAIJ,YAAW,MAAM,GAAG,MAAM;AACxB,MAAI,EAAE,uBAAuB,EAAE,mBAC7B,QAAO,EAAE,qBAAqB,EAAE;AAElC,SAAO,EAAE,oBAAoB,EAAE;GAC/B;AAEF,QAAO"}

package/dist/action-plan/aggregate-index-recommendations.d.cts

@@ -0,0 +1,36 @@
+'use client';
+
+import { IndexRecommendation } from "../query.cjs";
+import { AggregatedIndexRecommendation } from "./index-coverage.cjs";
+
+//#region src/action-plan/aggregate-index-recommendations.d.ts
+/**
+ * Minimal per-query shape the action-plan consolidation reads. Structurally
+ * compatible with both the live-query optimizer state and the CI run query
+ * result, so callers on either side can pass their records directly without an
+ * adapter. Only the `improvements_available` state carries index actions; every
+ * other state is ignored.
+ */
+interface ActionPlanQuery {
+  hash: string;
+  optimization: {
+    state: string;
+    cost?: number;
+    optimizedCost?: number;
+    costReductionPercentage?: number;
+    indexRecommendations?: IndexRecommendation[];
+  };
+}
+/**
+ * Collapse a set of analyzed queries into one entry per unique index
+ * definition, scored by the percentage cost reduction of the queries it helps.
+ *
+ * This is the shared primitive behind the live-query and CI-run recommendation
+ * views. Ranking here is the legacy "most queries, then biggest single
+ * percentage" order; the absolute-cost ranking the dashboard action plan needs
+ * lives in {@link buildActionPlan}.
+ */
+declare function aggregateIndexRecommendations(queries: readonly ActionPlanQuery[]): AggregatedIndexRecommendation[];
+//#endregion
+export { ActionPlanQuery, aggregateIndexRecommendations };
+//# sourceMappingURL=aggregate-index-recommendations.d.cts.map

package/dist/action-plan/aggregate-index-recommendations.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-index-recommendations.d.cts","names":[],"sources":["../../src/action-plan/aggregate-index-recommendations.ts"],"mappings":";;;;;;;;;AAUA;;;;UAAiB,eAAA;EACf,IAAA;EACA,YAAA;IACE,KAAA;IACA,IAAA;IACA,aAAA;IACA,uBAAA;IACA,oBAAA,GAAuB,mBAAA;EAAA;AAAA;AAa3B;;;;;;;;;AAAA,iBAAgB,6BAAA,CACd,OAAA,WAAkB,eAAA,KACjB,6BAAA"}

package/dist/action-plan/aggregate-index-recommendations.d.mts

@@ -0,0 +1,36 @@
+'use client';
+
+import { IndexRecommendation } from "../query.mjs";
+import { AggregatedIndexRecommendation } from "./index-coverage.mjs";
+
+//#region src/action-plan/aggregate-index-recommendations.d.ts
+/**
+ * Minimal per-query shape the action-plan consolidation reads. Structurally
+ * compatible with both the live-query optimizer state and the CI run query
+ * result, so callers on either side can pass their records directly without an
+ * adapter. Only the `improvements_available` state carries index actions; every
+ * other state is ignored.
+ */
+interface ActionPlanQuery {
+  hash: string;
+  optimization: {
+    state: string;
+    cost?: number;
+    optimizedCost?: number;
+    costReductionPercentage?: number;
+    indexRecommendations?: IndexRecommendation[];
+  };
+}
+/**
+ * Collapse a set of analyzed queries into one entry per unique index
+ * definition, scored by the percentage cost reduction of the queries it helps.
+ *
+ * This is the shared primitive behind the live-query and CI-run recommendation
+ * views. Ranking here is the legacy "most queries, then biggest single
+ * percentage" order; the absolute-cost ranking the dashboard action plan needs
+ * lives in {@link buildActionPlan}.
+ */
+declare function aggregateIndexRecommendations(queries: readonly ActionPlanQuery[]): AggregatedIndexRecommendation[];
+//#endregion
+export { ActionPlanQuery, aggregateIndexRecommendations };
+//# sourceMappingURL=aggregate-index-recommendations.d.mts.map

package/dist/action-plan/aggregate-index-recommendations.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-index-recommendations.d.mts","names":[],"sources":["../../src/action-plan/aggregate-index-recommendations.ts"],"mappings":";;;;;;;;;AAUA;;;;UAAiB,eAAA;EACf,IAAA;EACA,YAAA;IACE,KAAA;IACA,IAAA;IACA,aAAA;IACA,uBAAA;IACA,oBAAA,GAAuB,mBAAA;EAAA;AAAA;AAa3B;;;;;;;;;AAAA,iBAAgB,6BAAA,CACd,OAAA,WAAkB,eAAA,KACjB,6BAAA"}

package/dist/action-plan/aggregate-index-recommendations.mjs

@@ -0,0 +1,52 @@
+"use client";
+//#region src/action-plan/aggregate-index-recommendations.ts
+/**
+* Collapse a set of analyzed queries into one entry per unique index
+* definition, scored by the percentage cost reduction of the queries it helps.
+*
+* This is the shared primitive behind the live-query and CI-run recommendation
+* views. Ranking here is the legacy "most queries, then biggest single
+* percentage" order; the absolute-cost ranking the dashboard action plan needs
+* lives in {@link buildActionPlan}.
+*/
+function aggregateIndexRecommendations(queries) {
+	const indexMap = /* @__PURE__ */ new Map();
+	for (const query of queries) {
+		if (query.optimization.state !== "improvements_available") continue;
+		const { indexRecommendations, costReductionPercentage } = query.optimization;
+		if (!indexRecommendations || costReductionPercentage === void 0) continue;
+		for (const indexRec of indexRecommendations) {
+			const key = indexRec.definition;
+			const existing = indexMap.get(key);
+			if (existing) {
+				existing.queryHashes.push(query.hash);
+				existing.costReductions.push(costReductionPercentage);
+			} else indexMap.set(key, {
+				index: indexRec,
+				queryHashes: [query.hash],
+				costReductions: [costReductionPercentage]
+			});
+		}
+	}
+	const aggregated = [];
+	for (const data of indexMap.values()) {
+		const averageCostReduction = data.costReductions.reduce((sum, val) => sum + val, 0) / data.costReductions.length;
+		const bestCostReduction = Math.max(...data.costReductions);
+		aggregated.push({
+			index: data.index,
+			affectedQueryCount: data.queryHashes.length,
+			averageCostReduction,
+			bestCostReduction,
+			affectedQueryHashes: data.queryHashes
+		});
+	}
+	aggregated.sort((a, b) => {
+		if (a.affectedQueryCount !== b.affectedQueryCount) return b.affectedQueryCount - a.affectedQueryCount;
+		return b.bestCostReduction - a.bestCostReduction;
+	});
+	return aggregated;
+}
+//#endregion
+export { aggregateIndexRecommendations };
+
+//# sourceMappingURL=aggregate-index-recommendations.mjs.map

package/dist/action-plan/aggregate-index-recommendations.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate-index-recommendations.mjs","names":[],"sources":["../../src/action-plan/aggregate-index-recommendations.ts"],"sourcesContent":["import type { IndexRecommendation } from \"../query.js\";\nimport type { AggregatedIndexRecommendation } from \"./index-coverage.js\";\n\n/**\n * Minimal per-query shape the action-plan consolidation reads. Structurally\n * compatible with both the live-query optimizer state and the CI run query\n * result, so callers on either side can pass their records directly without an\n * adapter. Only the `improvements_available` state carries index actions; every\n * other state is ignored.\n */\nexport interface ActionPlanQuery {\n  hash: string;\n  optimization: {\n    state: string;\n    cost?: number;\n    optimizedCost?: number;\n    costReductionPercentage?: number;\n    indexRecommendations?: IndexRecommendation[];\n  };\n}\n\n/**\n * Collapse a set of analyzed queries into one entry per unique index\n * definition, scored by the percentage cost reduction of the queries it helps.\n *\n * This is the shared primitive behind the live-query and CI-run recommendation\n * views. Ranking here is the legacy \"most queries, then biggest single\n * percentage\" order; the absolute-cost ranking the dashboard action plan needs\n * lives in {@link buildActionPlan}.\n */\nexport function aggregateIndexRecommendations(\n  queries: readonly ActionPlanQuery[],\n): AggregatedIndexRecommendation[] {\n  const indexMap = new Map<\n    string,\n    {\n      index: IndexRecommendation;\n      queryHashes: string[];\n      costReductions: number[];\n    }\n  >();\n\n  for (const query of queries) {\n    if (query.optimization.state !== \"improvements_available\") continue;\n\n    const { indexRecommendations, costReductionPercentage } =\n      query.optimization;\n    if (!indexRecommendations || costReductionPercentage === undefined)\n      continue;\n\n    for (const indexRec of indexRecommendations) {\n      const key = indexRec.definition;\n      const existing = indexMap.get(key);\n\n      if (existing) {\n        existing.queryHashes.push(query.hash);\n        existing.costReductions.push(costReductionPercentage);\n      } else {\n        indexMap.set(key, {\n          index: indexRec,\n          queryHashes: [query.hash],\n          costReductions: [costReductionPercentage],\n        });\n      }\n    }\n  }\n\n  const aggregated: AggregatedIndexRecommendation[] = [];\n\n  for (const data of indexMap.values()) {\n    const averageCostReduction =\n      data.costReductions.reduce((sum, val) => sum + val, 0) /\n      data.costReductions.length;\n    const bestCostReduction = Math.max(...data.costReductions);\n\n    aggregated.push({\n      index: data.index,\n      affectedQueryCount: data.queryHashes.length,\n      averageCostReduction,\n      bestCostReduction,\n      affectedQueryHashes: data.queryHashes,\n    });\n  }\n\n  // Most affected queries first, breaking ties by the biggest single reduction.\n  aggregated.sort((a, b) => {\n    if (a.affectedQueryCount !== b.affectedQueryCount) {\n      return b.affectedQueryCount - a.affectedQueryCount;\n    }\n    return b.bestCostReduction - a.bestCostReduction;\n  });\n\n  return aggregated;\n}\n"],"mappings":";;;;;;;;;;;AA8BA,SAAgB,8BACd,SACiC;CACjC,MAAM,2BAAW,IAAI,KAOlB;AAEH,MAAK,MAAM,SAAS,SAAS;AAC3B,MAAI,MAAM,aAAa,UAAU,yBAA0B;EAE3D,MAAM,EAAE,sBAAsB,4BAC5B,MAAM;AACR,MAAI,CAAC,wBAAwB,4BAA4B,KAAA,EACvD;AAEF,OAAK,MAAM,YAAY,sBAAsB;GAC3C,MAAM,MAAM,SAAS;GACrB,MAAM,WAAW,SAAS,IAAI,IAAI;AAElC,OAAI,UAAU;AACZ,aAAS,YAAY,KAAK,MAAM,KAAK;AACrC,aAAS,eAAe,KAAK,wBAAwB;SAErD,UAAS,IAAI,KAAK;IAChB,OAAO;IACP,aAAa,CAAC,MAAM,KAAK;IACzB,gBAAgB,CAAC,wBAAwB;IAC1C,CAAC;;;CAKR,MAAM,aAA8C,EAAE;AAEtD,MAAK,MAAM,QAAQ,SAAS,QAAQ,EAAE;EACpC,MAAM,uBACJ,KAAK,eAAe,QAAQ,KAAK,QAAQ,MAAM,KAAK,EAAE,GACtD,KAAK,eAAe;EACtB,MAAM,oBAAoB,KAAK,IAAI,GAAG,KAAK,eAAe;AAE1D,aAAW,KAAK;GACd,OAAO,KAAK;GACZ,oBAAoB,KAAK,YAAY;GACrC;GACA;GACA,qBAAqB,KAAK;GAC3B,CAAC;;AAIJ,YAAW,MAAM,GAAG,MAAM;AACxB,MAAI,EAAE,uBAAuB,EAAE,mBAC7B,QAAO,EAAE,qBAAqB,EAAE;AAElC,SAAO,EAAE,oBAAoB,EAAE;GAC/B;AAEF,QAAO"}

package/dist/action-plan/build-action-plan.cjs

@@ -0,0 +1,179 @@
+"use client";
+const require_index_coverage = require("./index-coverage.cjs");
+const require_aggregate_index_recommendations = require("./aggregate-index-recommendations.cjs");
+//#region src/action-plan/build-action-plan.ts
+/**
+* Severity → ranking weight, mirroring `NUDGE_SEVERITY_WEIGHTS` in
+* `apps/app/src/components/nudge-scoring.ts`. Duplicated because core cannot
+* import from the app; keep the two in sync. Drives both a card's placement
+* (its top severity) and the within-tier sort (summed weight).
+*/
+const NUDGE_SEVERITY_WEIGHT = {
+	CRITICAL: 16,
+	WARNING: 4,
+	INFO: 1
+};
+/**
+* Optimizer-emitted nudges that announce an available improvement rather than a
+* query anti-pattern. The index win they describe is already a `index` step, so
+* they never become a nudge action.
+*/
+const NON_ANTIPATTERN_NUDGE_KINDS = new Set(["LARGE_IMPROVEMENT_FOUND", "SMALL_IMPROVEMENT_FOUND"]);
+/**
+* Consolidate analyzed queries and detected regressions into one prioritized
+* action plan.
+*
+* - Tiering is positional across kinds: regression → CRITICAL nudge → index →
+*   WARNING nudge → INFO nudge. A regression or critical anti-pattern (both
+*   "something is wrong") outranks an index suggestion ("do this to improve");
+*   lower-severity advice falls below it. Cross-kind `value`s carry different
+*   units and are never compared. Within regressions, sort by
+*   `increasePercentage` descending; within indexes, by summed absolute cost
+*   reduction; within a nudge tier, by summed severity weight.
+* - Index bundling: one step per domain (table). Non-overlapping indexes on the
+*   same table share a step; a covering `(a,b,c)` absorbs `(a,b)`.
+* - Index ranking: summed absolute cost reduction (`cost - optimizedCost`) over
+*   the UNION of affected query hashes, each query counted once.
+* - Nudge bundling: one step per query, carrying all its anti-pattern findings;
+*   the step's tier is the query's highest severity.
+*
+* Callers are expected to pass current-state, latest-per-hash queries; this
+* module does not gate on age or recency.
+*/
+function buildActionPlan(queries, regressions = [], nudgeQueries = []) {
+	const nudges = buildNudgeSteps(nudgeQueries);
+	const bySeverity = (severity) => nudges.filter((step) => step.severity === severity);
+	return [
+		...buildRegressionSteps(regressions),
+		...bySeverity("CRITICAL"),
+		...buildIndexSteps(queries),
+		...bySeverity("WARNING"),
+		...bySeverity("INFO")
+	];
+}
+function buildRegressionSteps(regressions) {
+	return regressions.map((breach) => ({
+		kind: "regression",
+		key: contentHash(`regression|${breach.queryHash}`),
+		queryHash: breach.queryHash,
+		cost: breach.cost,
+		baselineCost: breach.baselineCost,
+		increasePercentage: breach.increasePercentage,
+		value: breach.increasePercentage
+	})).sort((a, b) => {
+		if (b.value !== a.value) return b.value - a.value;
+		return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+	});
+}
+function buildNudgeSteps(nudgeQueries) {
+	const steps = [];
+	for (const { hash, nudges } of nudgeQueries) {
+		const findings = nudges.filter((n) => !NON_ANTIPATTERN_NUDGE_KINDS.has(n.kind)).map((n) => ({
+			kind: n.kind,
+			severity: n.severity,
+			message: n.message
+		})).sort((a, b) => {
+			const weight = NUDGE_SEVERITY_WEIGHT[b.severity] - NUDGE_SEVERITY_WEIGHT[a.severity];
+			if (weight !== 0) return weight;
+			return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;
+		});
+		if (findings.length === 0) continue;
+		const value = findings.reduce((sum, f) => sum + NUDGE_SEVERITY_WEIGHT[f.severity], 0);
+		steps.push({
+			kind: "nudge",
+			key: contentHash(`nudge|${hash}`),
+			queryHash: hash,
+			nudges: findings,
+			severity: findings[0].severity,
+			value
+		});
+	}
+	return steps.sort((a, b) => {
+		if (b.value !== a.value) return b.value - a.value;
+		return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+	});
+}
+function buildIndexSteps(queries) {
+	const queryCost = /* @__PURE__ */ new Map();
+	for (const query of queries) {
+		const o = query.optimization;
+		if (o.state === "improvements_available" && o.cost !== void 0 && o.optimizedCost !== void 0 && !queryCost.has(query.hash)) queryCost.set(query.hash, {
+			cost: o.cost,
+			optimizedCost: o.optimizedCost
+		});
+	}
+	const byDomain = /* @__PURE__ */ new Map();
+	for (const rec of require_aggregate_index_recommendations.aggregateIndexRecommendations(queries)) {
+		const domain = `${rec.index.schema}.${rec.index.table}`;
+		const bucket = byDomain.get(domain);
+		if (bucket) bucket.push(rec);
+		else byDomain.set(domain, [rec]);
+	}
+	const steps = [];
+	for (const [domain, recs] of byDomain) {
+		const indexes = require_index_coverage.groupIndexesByCoverage(recs).map((group) => {
+			const hashes = new Set(group.primary.affectedQueryHashes);
+			for (const covered of group.covered) for (const hash of covered.affectedQueryHashes) hashes.add(hash);
+			return {
+				op: "create",
+				definition: group.primary.index.definition,
+				columns: group.primary.index.columns,
+				coveredDefinitions: group.covered.map((c) => c.index.definition),
+				affectedQueryHashes: [...hashes].sort()
+			};
+		});
+		const stepHashes = /* @__PURE__ */ new Set();
+		for (const action of indexes) {
+			if (action.op !== "create") continue;
+			for (const hash of action.affectedQueryHashes) if (queryCost.has(hash)) stepHashes.add(hash);
+		}
+		const affectedQueries = [...stepHashes].sort().map((hash) => {
+			const cost = queryCost.get(hash);
+			return {
+				hash,
+				cost: cost.cost,
+				optimizedCost: cost.optimizedCost
+			};
+		});
+		if (affectedQueries.length === 0) continue;
+		const reductions = affectedQueries.map((q) => q.cost - q.optimizedCost);
+		const total = reductions.reduce((sum, val) => sum + val, 0);
+		const best = Math.max(...reductions);
+		steps.push({
+			kind: "index",
+			key: stepKey(domain, indexes),
+			domain,
+			indexes,
+			affectedQueryCount: affectedQueries.length,
+			affectedQueries,
+			costReduction: {
+				average: total / reductions.length,
+				best,
+				total
+			},
+			value: total
+		});
+	}
+	steps.sort((a, b) => {
+		if (b.value !== a.value) return b.value - a.value;
+		if (b.affectedQueryCount !== a.affectedQueryCount) return b.affectedQueryCount - a.affectedQueryCount;
+		return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+	});
+	return steps;
+}
+function stepKey(domain, indexes) {
+	return contentHash(`${domain}|${indexes.map((action) => `${action.op}:${action.definition}`).sort().join("|")}`);
+}
+/** FNV-1a 32-bit hash → 8-char hex. Deterministic and dependency-free. */
+function contentHash(input) {
+	let hash = 2166136261;
+	for (let i = 0; i < input.length; i++) {
+		hash ^= input.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+//#endregion
+exports.buildActionPlan = buildActionPlan;
+
+//# sourceMappingURL=build-action-plan.cjs.map

package/dist/action-plan/build-action-plan.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-action-plan.cjs","names":["aggregateIndexRecommendations","groupIndexesByCoverage"],"sources":["../../src/action-plan/build-action-plan.ts"],"sourcesContent":["import type { IndexRecommendation } from \"../query.js\";\nimport type { Nudge } from \"../sql/nudges.js\";\nimport {\n  aggregateIndexRecommendations,\n  type ActionPlanQuery,\n} from \"./aggregate-index-recommendations.js\";\nimport {\n  groupIndexesByCoverage,\n  type AggregatedIndexRecommendation,\n} from \"./index-coverage.js\";\n\n/**\n * Bundling key for a step. v0.9/v1 = the affected table (`schema.table`);\n * #3100 widens this to a table-cluster.\n */\nexport type DomainLabel = string;\n\ntype IndexActionColumns = IndexRecommendation[\"columns\"];\n\n/**\n * One index change inside a step. A step is a unit of work applied in one go,\n * so it carries 1..N of these. Only `create` ships in #3098; the `drop` variant\n * exists for the type and lands with full-DB unused detection (#3120).\n */\nexport type IndexAction =\n  | {\n      op: \"create\";\n      definition: string;\n      columns: IndexActionColumns;\n      /** Prefix indexes this one absorbs (covering `(a,b,c)` absorbs `(a,b)`). */\n      coveredDefinitions: string[];\n      /** Union of query hashes this create helps, including absorbed prefixes. */\n      affectedQueryHashes: string[];\n    }\n  | { op: \"drop\"; definition: string; reason: \"unused\" | \"redundant\" };\n\n/** Before/after planner cost for one query the step affects. */\nexport interface AffectedQueryCost {\n  hash: string;\n  cost: number;\n  optimizedCost: number;\n}\n\nexport interface CostReduction {\n  average: number;\n  best: number;\n  total: number;\n}\n\n/**\n * A query whose cost rose past the configured regression threshold. The caller\n * (which owns the threshold config and the shared cost-delta rounding contract)\n * detects the breach; this module only shapes and ranks it.\n */\nexport interface RegressionBreach {\n  queryHash: string;\n  /** Current planner cost. */\n  cost: number;\n  /** Baseline cost the breach is measured against. */\n  baselineCost: number;\n  /** Increase over baseline, in percent. Pre-rounded by the caller. */\n  increasePercentage: number;\n}\n\n/** A single anti-pattern finding shown inside a nudge step. */\nexport type NudgeFinding = Pick<Nudge, \"kind\" | \"severity\" | \"message\">;\n\n/**\n * One analyzed query plus its anti-pattern nudges, scoped current-state by the\n * caller. The two synthetic optimizer nudges (`*_IMPROVEMENT_FOUND`) are not\n * anti-patterns — they restate the index win — and are dropped here, not by the\n * caller.\n */\nexport interface ActionPlanNudgeQuery {\n  hash: string;\n  nudges: readonly Nudge[];\n}\n\n/**\n * Severity → ranking weight, mirroring `NUDGE_SEVERITY_WEIGHTS` in\n * `apps/app/src/components/nudge-scoring.ts`. Duplicated because core cannot\n * import from the app; keep the two in sync. Drives both a card's placement\n * (its top severity) and the within-tier sort (summed weight).\n */\nconst NUDGE_SEVERITY_WEIGHT: Record<Nudge[\"severity\"], number> = {\n  CRITICAL: 16,\n  WARNING: 4,\n  INFO: 1,\n};\n\n/**\n * Optimizer-emitted nudges that announce an available improvement rather than a\n * query anti-pattern. The index win they describe is already a `index` step, so\n * they never become a nudge action.\n */\nconst NON_ANTIPATTERN_NUDGE_KINDS = new Set<Nudge[\"kind\"]>([\n  \"LARGE_IMPROVEMENT_FOUND\",\n  \"SMALL_IMPROVEMENT_FOUND\",\n]);\n\n/**\n * A prioritized recommendation in the database-health action plan, a\n * discriminated union over action kinds: `index` (#3098), `regression` (#3099)\n * and `nudge` (#3102).\n *\n * Tiering across kinds is positional, not by `value` — the kinds' `value`\n * scores carry different units and are never compared across tiers. The order\n * is regression → CRITICAL nudge → index → WARNING nudge → INFO nudge: a\n * \"something got worse\" signal and a critical anti-pattern outrank a \"do this\n * to improve\" suggestion, while lower-severity advice falls below it. See\n * {@link buildActionPlan}.\n */\nexport type ActionableStep =\n  | {\n      kind: \"index\";\n      /**\n       * Stable, content-derived identity: hash(domain + sorted index ops). Used\n       * as the React key, the client freeze-diff key, and future triage identity.\n       */\n      key: string;\n      domain: DomainLabel;\n      /** 1..N index actions bundled for this domain. */\n      indexes: IndexAction[];\n      /** UNION of affected query hashes across the bundle — never a sum. */\n      affectedQueryCount: number;\n      /** Per-affected-query before/after cost, for display. */\n      affectedQueries: AffectedQueryCost[];\n      costReduction: CostReduction;\n      /** Ranking score = total absolute reduction. Hidden from the user. */\n      value: number;\n    }\n  | {\n      kind: \"regression\";\n      /** Stable, content-derived identity: hash(\"regression\" + queryHash). */\n      key: string;\n      queryHash: string;\n      cost: number;\n      baselineCost: number;\n      increasePercentage: number;\n      /** Within-tier ranking score = increasePercentage. Hidden from the user. */\n      value: number;\n    }\n  | {\n      kind: \"nudge\";\n      /** Stable, content-derived identity: hash(\"nudge\" + queryHash). */\n      key: string;\n      queryHash: string;\n      /** The query's anti-pattern findings, highest severity first. */\n      nudges: NudgeFinding[];\n      /** Highest severity across the findings — sets the card's tier. */\n      severity: Nudge[\"severity\"];\n      /** Within-tier ranking score = summed severity weight. Hidden. */\n      value: number;\n    };\n\n/**\n * Consolidate analyzed queries and detected regressions into one prioritized\n * action plan.\n *\n * - Tiering is positional across kinds: regression → CRITICAL nudge → index →\n *   WARNING nudge → INFO nudge. A regression or critical anti-pattern (both\n *   \"something is wrong\") outranks an index suggestion (\"do this to improve\");\n *   lower-severity advice falls below it. Cross-kind `value`s carry different\n *   units and are never compared. Within regressions, sort by\n *   `increasePercentage` descending; within indexes, by summed absolute cost\n *   reduction; within a nudge tier, by summed severity weight.\n * - Index bundling: one step per domain (table). Non-overlapping indexes on the\n *   same table share a step; a covering `(a,b,c)` absorbs `(a,b)`.\n * - Index ranking: summed absolute cost reduction (`cost - optimizedCost`) over\n *   the UNION of affected query hashes, each query counted once.\n * - Nudge bundling: one step per query, carrying all its anti-pattern findings;\n *   the step's tier is the query's highest severity.\n *\n * Callers are expected to pass current-state, latest-per-hash queries; this\n * module does not gate on age or recency.\n */\nexport function buildActionPlan(\n  queries: readonly ActionPlanQuery[],\n  regressions: readonly RegressionBreach[] = [],\n  nudgeQueries: readonly ActionPlanNudgeQuery[] = [],\n): ActionableStep[] {\n  const nudges = buildNudgeSteps(nudgeQueries);\n  const bySeverity = (severity: Nudge[\"severity\"]) =>\n    nudges.filter((step) => step.severity === severity);\n\n  // Positional tiers, each block already internally sorted. Critical nudges sit\n  // above indexes; warning/info advice sits below.\n  return [\n    ...buildRegressionSteps(regressions),\n    ...bySeverity(\"CRITICAL\"),\n    ...buildIndexSteps(queries),\n    ...bySeverity(\"WARNING\"),\n    ...bySeverity(\"INFO\"),\n  ];\n}\n\nfunction buildRegressionSteps(\n  regressions: readonly RegressionBreach[],\n): ActionableStep[] {\n  return regressions\n    .map(\n      (breach): ActionableStep => ({\n        kind: \"regression\",\n        key: contentHash(`regression|${breach.queryHash}`),\n        queryHash: breach.queryHash,\n        cost: breach.cost,\n        baselineCost: breach.baselineCost,\n        increasePercentage: breach.increasePercentage,\n        value: breach.increasePercentage,\n      }),\n    )\n    .sort((a, b) => {\n      if (b.value !== a.value) return b.value - a.value;\n      // Deterministic tie-break by query identity for a stable render order.\n      return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;\n    });\n}\n\nfunction buildNudgeSteps(\n  nudgeQueries: readonly ActionPlanNudgeQuery[],\n): Extract<ActionableStep, { kind: \"nudge\" }>[] {\n  const steps: Extract<ActionableStep, { kind: \"nudge\" }>[] = [];\n  for (const { hash, nudges } of nudgeQueries) {\n    const findings: NudgeFinding[] = nudges\n      .filter((n) => !NON_ANTIPATTERN_NUDGE_KINDS.has(n.kind))\n      .map((n) => ({ kind: n.kind, severity: n.severity, message: n.message }))\n      // Highest-severity finding first; stable by kind for a deterministic order.\n      .sort((a, b) => {\n        const weight =\n          NUDGE_SEVERITY_WEIGHT[b.severity] - NUDGE_SEVERITY_WEIGHT[a.severity];\n        if (weight !== 0) return weight;\n        return a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0;\n      });\n\n    if (findings.length === 0) continue;\n\n    const value = findings.reduce(\n      (sum, f) => sum + NUDGE_SEVERITY_WEIGHT[f.severity],\n      0,\n    );\n    steps.push({\n      kind: \"nudge\",\n      key: contentHash(`nudge|${hash}`),\n      queryHash: hash,\n      nudges: findings,\n      // Findings are severity-sorted, so the first is the card's top severity.\n      severity: findings[0]!.severity,\n      value,\n    });\n  }\n\n  // Most severe first; deterministic tie-break by query identity. The caller\n  // partitions these into the CRITICAL / WARNING / INFO tiers, preserving order.\n  return steps.sort((a, b) => {\n    if (b.value !== a.value) return b.value - a.value;\n    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;\n  });\n}\n\nfunction buildIndexSteps(\n  queries: readonly ActionPlanQuery[],\n): ActionableStep[] {\n  // Each query's own before/after cost, used for the absolute ranking. A hash\n  // appears once — the first improvements state we see for it wins.\n  const queryCost = new Map<string, { cost: number; optimizedCost: number }>();\n  for (const query of queries) {\n    const o = query.optimization;\n    if (\n      o.state === \"improvements_available\" &&\n      o.cost !== undefined &&\n      o.optimizedCost !== undefined &&\n      !queryCost.has(query.hash)\n    ) {\n      queryCost.set(query.hash, {\n        cost: o.cost,\n        optimizedCost: o.optimizedCost,\n      });\n    }\n  }\n\n  // Reuse the shared per-definition consolidation, then bundle by table.\n  const byDomain = new Map<DomainLabel, AggregatedIndexRecommendation[]>();\n  for (const rec of aggregateIndexRecommendations(queries)) {\n    const domain = `${rec.index.schema}.${rec.index.table}`;\n    const bucket = byDomain.get(domain);\n    if (bucket) bucket.push(rec);\n    else byDomain.set(domain, [rec]);\n  }\n\n  const steps: Extract<ActionableStep, { kind: \"index\" }>[] = [];\n  for (const [domain, recs] of byDomain) {\n    const indexes: IndexAction[] = groupIndexesByCoverage(recs).map((group) => {\n      const hashes = new Set(group.primary.affectedQueryHashes);\n      for (const covered of group.covered) {\n        for (const hash of covered.affectedQueryHashes) hashes.add(hash);\n      }\n      return {\n        op: \"create\",\n        definition: group.primary.index.definition,\n        columns: group.primary.index.columns,\n        coveredDefinitions: group.covered.map((c) => c.index.definition),\n        affectedQueryHashes: [...hashes].sort(),\n      };\n    });\n\n    // Step-level union of scorable queries (those with a known before/after).\n    const stepHashes = new Set<string>();\n    for (const action of indexes) {\n      if (action.op !== \"create\") continue;\n      for (const hash of action.affectedQueryHashes) {\n        if (queryCost.has(hash)) stepHashes.add(hash);\n      }\n    }\n\n    const affectedQueries: AffectedQueryCost[] = [...stepHashes]\n      .sort()\n      .map((hash) => {\n        const cost = queryCost.get(hash)!;\n        return { hash, cost: cost.cost, optimizedCost: cost.optimizedCost };\n      });\n\n    if (affectedQueries.length === 0) continue;\n\n    const reductions = affectedQueries.map((q) => q.cost - q.optimizedCost);\n    const total = reductions.reduce((sum, val) => sum + val, 0);\n    const best = Math.max(...reductions);\n\n    steps.push({\n      kind: \"index\",\n      key: stepKey(domain, indexes),\n      domain,\n      indexes,\n      affectedQueryCount: affectedQueries.length,\n      affectedQueries,\n      costReduction: { average: total / reductions.length, best, total },\n      value: total,\n    });\n  }\n\n  // Most valuable first; deterministic tie-breaks for a stable render order.\n  steps.sort((a, b) => {\n    if (b.value !== a.value) return b.value - a.value;\n    if (b.affectedQueryCount !== a.affectedQueryCount) {\n      return b.affectedQueryCount - a.affectedQueryCount;\n    }\n    return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;\n  });\n\n  return steps;\n}\n\nfunction stepKey(domain: DomainLabel, indexes: IndexAction[]): string {\n  const parts = indexes\n    .map((action) => `${action.op}:${action.definition}`)\n    .sort();\n  return contentHash(`${domain}|${parts.join(\"|\")}`);\n}\n\n/** FNV-1a 32-bit hash → 8-char hex. Deterministic and dependency-free. */\nfunction contentHash(input: string): string {\n  let hash = 0x811c9dc5;\n  for (let i = 0; i < input.length; i++) {\n    hash ^= input.charCodeAt(i);\n    hash = Math.imul(hash, 0x01000193);\n  }\n  return (hash >>> 0).toString(16).padStart(8, \"0\");\n}\n"],"mappings":"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"}

package/dist/action-plan/build-action-plan.d.cts

@@ -0,0 +1,132 @@
+'use client';
+
+import { Nudge } from "../sql/nudges.cjs";
+import { IndexRecommendation } from "../query.cjs";
+import { ActionPlanQuery } from "./aggregate-index-recommendations.cjs";
+
+//#region src/action-plan/build-action-plan.d.ts
+/**
+ * Bundling key for a step. v0.9/v1 = the affected table (`schema.table`);
+ * #3100 widens this to a table-cluster.
+ */
+type DomainLabel = string;
+type IndexActionColumns = IndexRecommendation["columns"];
+/**
+ * One index change inside a step. A step is a unit of work applied in one go,
+ * so it carries 1..N of these. Only `create` ships in #3098; the `drop` variant
+ * exists for the type and lands with full-DB unused detection (#3120).
+ */
+type IndexAction = {
+  op: "create";
+  definition: string;
+  columns: IndexActionColumns; /** Prefix indexes this one absorbs (covering `(a,b,c)` absorbs `(a,b)`). */
+  coveredDefinitions: string[]; /** Union of query hashes this create helps, including absorbed prefixes. */
+  affectedQueryHashes: string[];
+} | {
+  op: "drop";
+  definition: string;
+  reason: "unused" | "redundant";
+};
+/** Before/after planner cost for one query the step affects. */
+interface AffectedQueryCost {
+  hash: string;
+  cost: number;
+  optimizedCost: number;
+}
+interface CostReduction {
+  average: number;
+  best: number;
+  total: number;
+}
+/**
+ * A query whose cost rose past the configured regression threshold. The caller
+ * (which owns the threshold config and the shared cost-delta rounding contract)
+ * detects the breach; this module only shapes and ranks it.
+ */
+interface RegressionBreach {
+  queryHash: string;
+  /** Current planner cost. */
+  cost: number;
+  /** Baseline cost the breach is measured against. */
+  baselineCost: number;
+  /** Increase over baseline, in percent. Pre-rounded by the caller. */
+  increasePercentage: number;
+}
+/** A single anti-pattern finding shown inside a nudge step. */
+type NudgeFinding = Pick<Nudge, "kind" | "severity" | "message">;
+/**
+ * One analyzed query plus its anti-pattern nudges, scoped current-state by the
+ * caller. The two synthetic optimizer nudges (`*_IMPROVEMENT_FOUND`) are not
+ * anti-patterns — they restate the index win — and are dropped here, not by the
+ * caller.
+ */
+interface ActionPlanNudgeQuery {
+  hash: string;
+  nudges: readonly Nudge[];
+}
+/**
+ * A prioritized recommendation in the database-health action plan, a
+ * discriminated union over action kinds: `index` (#3098), `regression` (#3099)
+ * and `nudge` (#3102).
+ *
+ * Tiering across kinds is positional, not by `value` — the kinds' `value`
+ * scores carry different units and are never compared across tiers. The order
+ * is regression → CRITICAL nudge → index → WARNING nudge → INFO nudge: a
+ * "something got worse" signal and a critical anti-pattern outrank a "do this
+ * to improve" suggestion, while lower-severity advice falls below it. See
+ * {@link buildActionPlan}.
+ */
+type ActionableStep = {
+  kind: "index";
+  /**
+   * Stable, content-derived identity: hash(domain + sorted index ops). Used
+   * as the React key, the client freeze-diff key, and future triage identity.
+   */
+  key: string;
+  domain: DomainLabel; /** 1..N index actions bundled for this domain. */
+  indexes: IndexAction[]; /** UNION of affected query hashes across the bundle — never a sum. */
+  affectedQueryCount: number; /** Per-affected-query before/after cost, for display. */
+  affectedQueries: AffectedQueryCost[];
+  costReduction: CostReduction; /** Ranking score = total absolute reduction. Hidden from the user. */
+  value: number;
+} | {
+  kind: "regression"; /** Stable, content-derived identity: hash("regression" + queryHash). */
+  key: string;
+  queryHash: string;
+  cost: number;
+  baselineCost: number;
+  increasePercentage: number; /** Within-tier ranking score = increasePercentage. Hidden from the user. */
+  value: number;
+} | {
+  kind: "nudge"; /** Stable, content-derived identity: hash("nudge" + queryHash). */
+  key: string;
+  queryHash: string; /** The query's anti-pattern findings, highest severity first. */
+  nudges: NudgeFinding[]; /** Highest severity across the findings — sets the card's tier. */
+  severity: Nudge["severity"]; /** Within-tier ranking score = summed severity weight. Hidden. */
+  value: number;
+};
+/**
+ * Consolidate analyzed queries and detected regressions into one prioritized
+ * action plan.
+ *
+ * - Tiering is positional across kinds: regression → CRITICAL nudge → index →
+ *   WARNING nudge → INFO nudge. A regression or critical anti-pattern (both
+ *   "something is wrong") outranks an index suggestion ("do this to improve");
+ *   lower-severity advice falls below it. Cross-kind `value`s carry different
+ *   units and are never compared. Within regressions, sort by
+ *   `increasePercentage` descending; within indexes, by summed absolute cost
+ *   reduction; within a nudge tier, by summed severity weight.
+ * - Index bundling: one step per domain (table). Non-overlapping indexes on the
+ *   same table share a step; a covering `(a,b,c)` absorbs `(a,b)`.
+ * - Index ranking: summed absolute cost reduction (`cost - optimizedCost`) over
+ *   the UNION of affected query hashes, each query counted once.
+ * - Nudge bundling: one step per query, carrying all its anti-pattern findings;
+ *   the step's tier is the query's highest severity.
+ *
+ * Callers are expected to pass current-state, latest-per-hash queries; this
+ * module does not gate on age or recency.
+ */
+declare function buildActionPlan(queries: readonly ActionPlanQuery[], regressions?: readonly RegressionBreach[], nudgeQueries?: readonly ActionPlanNudgeQuery[]): ActionableStep[];
+//#endregion
+export { ActionPlanNudgeQuery, ActionableStep, AffectedQueryCost, CostReduction, DomainLabel, IndexAction, NudgeFinding, RegressionBreach, buildActionPlan };
+//# sourceMappingURL=build-action-plan.d.cts.map

package/dist/action-plan/build-action-plan.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-action-plan.d.cts","names":[],"sources":["../../src/action-plan/build-action-plan.ts"],"mappings":";;;;;;;;;;AAeA;KAAY,WAAA;AAAA,KAEP,kBAAA,GAAqB,mBAAA;;;AAFO;;;KASrB,WAAA;EAEN,EAAA;EACA,UAAA;EACA,OAAA,EAAS,kBAAA;EAET,kBAAA,YAJA;EAMA,mBAAA;AAAA;EAEA,EAAA;EAAY,UAAA;EAAoB,MAAA;AAAA;;UAGrB,iBAAA;EACf,IAAA;EACA,IAAA;EACA,aAAA;AAAA;AAAA,UAGe,aAAA;EACf,OAAA;EACA,IAAA;EACA,KAAA;AAAA;;;AAHF;;;UAWiB,gBAAA;EACf,SAAA;EAVA;EAYA,IAAA;EAXK;EAaL,YAAA;EALe;EAOf,kBAAA;AAAA;;KAIU,YAAA,GAAe,IAAA,CAAK,KAAA;;;;;;AAAhC;UAQiB,oBAAA;EACf,IAAA;EACA,MAAA,WAAiB,KAAA;AAAA;AAFnB;;;;;;;;;AAuCA;;;AAvCA,KAuCY,cAAA;EAEN,IAAA;EAYiB;;;;EAPjB,GAAA;EACA,MAAA,EAAQ,WAAA,EANR;EAQA,OAAA,EAAS,WAAA,IAFT;EAIA,kBAAA,UAFA;EAIA,eAAA,EAAiB,iBAAA;EACjB,aAAA,EAAe,aAAA,EADf;EAGA,KAAA;AAAA;EAGA,IAAA,gBAHA;EAKA,GAAA;EACA,SAAA;EACA,IAAA;EACA,YAAA;EACA,kBAAA;EAEA,KAAA;AAAA;EAGA,IAAA,WAGA;EADA,GAAA;EACA,SAAA,UAIA;EAFA,MAAA,EAAQ,YAAA,IAIR;EAFA,QAAA,EAAU,KAAA,cAEL;EAAL,KAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;iBAwBU,eAAA,CACd,OAAA,WAAkB,eAAA,IAClB,WAAA,YAAsB,gBAAA,IACtB,YAAA,YAAuB,oBAAA,KACtB,cAAA"}