@query-doctor/core 0.10.2 → 0.10.4

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

@@ -0,0 +1,132 @@
+'use client';
+
+import { Nudge } from "../sql/nudges.mjs";
+import { IndexRecommendation } from "../query.mjs";
+import { ActionPlanQuery } from "./aggregate-index-recommendations.mjs";
+
+//#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.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-action-plan.d.mts","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"}

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

@@ -0,0 +1,179 @@
+"use client";
+import { groupIndexesByCoverage } from "./index-coverage.mjs";
+import { aggregateIndexRecommendations } from "./aggregate-index-recommendations.mjs";
+//#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 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 = 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
+export { buildActionPlan };
+
+//# sourceMappingURL=build-action-plan.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-action-plan.mjs","names":[],"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/index-coverage.cjs

@@ -0,0 +1,72 @@
+"use client";
+//#region src/action-plan/index-coverage.ts
+/**
+* Check if indexA covers indexB (A is a superset that includes B as a prefix).
+*
+* Rules:
+* - Same schema and table
+* - A's columns start with B's columns (B is a prefix of A)
+* - Sort directions must match for prefix columns
+* - WHERE clauses must be compatible
+*
+* Examples:
+* - (a, b, c) covers (a, b) and (a)
+* - (a DESC, b) covers (a DESC) but NOT (a ASC)
+*/
+function indexCovers(a, b) {
+	if (a.schema !== b.schema || a.table !== b.table) return false;
+	if (a.columns.length <= b.columns.length) return false;
+	for (let i = 0; i < b.columns.length; i++) {
+		const colA = a.columns[i];
+		const colB = b.columns[i];
+		if (colA.column !== colB.column) return false;
+		if (normalizeSort(colA.sort) !== normalizeSort(colB.sort)) return false;
+	}
+	if (b.where && a.where !== b.where) return false;
+	return true;
+}
+function normalizeSort(sort) {
+	if (!sort) return "ASC";
+	if (typeof sort === "string") return sort.toUpperCase();
+	if (typeof sort === "object" && sort !== null && "dir" in sort) {
+		if (sort.dir === "SORTBY_DESC") return "DESC";
+		return "ASC";
+	}
+	return "ASC";
+}
+/**
+* Group indexes by coverage relationships.
+*
+* Returns groups where each group has a "primary" index that covers
+* zero or more "covered" indexes. Indexes that don't cover or aren't
+* covered by any other index become their own single-item group.
+*/
+function groupIndexesByCoverage(indexes) {
+	if (indexes.length === 0) return [];
+	const coveredSet = /* @__PURE__ */ new Set();
+	const groups = [];
+	const sorted = [...indexes].sort((a, b) => b.index.columns.length - a.index.columns.length);
+	for (const idx of sorted) {
+		const key = idx.index.definition;
+		if (coveredSet.has(key)) continue;
+		const covered = [];
+		for (const other of sorted) {
+			if (other.index.definition === key) continue;
+			if (coveredSet.has(other.index.definition)) continue;
+			if (indexCovers(idx.index, other.index)) {
+				covered.push(other);
+				coveredSet.add(other.index.definition);
+			}
+		}
+		groups.push({
+			primary: idx,
+			covered
+		});
+	}
+	return groups;
+}
+//#endregion
+exports.groupIndexesByCoverage = groupIndexesByCoverage;
+exports.indexCovers = indexCovers;
+
+//# sourceMappingURL=index-coverage.cjs.map

package/dist/action-plan/index-coverage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-coverage.cjs","names":[],"sources":["../../src/action-plan/index-coverage.ts"],"sourcesContent":["import type { IndexRecommendation } from \"../query.js\";\n\n/** A unique index recommendation plus how it scored across the queries it helps. */\nexport interface AggregatedIndexRecommendation {\n  index: IndexRecommendation;\n  affectedQueryCount: number;\n  averageCostReduction: number;\n  bestCostReduction: number;\n  affectedQueryHashes: string[];\n}\n\n/**\n * Check if indexA covers indexB (A is a superset that includes B as a prefix).\n *\n * Rules:\n * - Same schema and table\n * - A's columns start with B's columns (B is a prefix of A)\n * - Sort directions must match for prefix columns\n * - WHERE clauses must be compatible\n *\n * Examples:\n * - (a, b, c) covers (a, b) and (a)\n * - (a DESC, b) covers (a DESC) but NOT (a ASC)\n */\nexport function indexCovers(\n  a: IndexRecommendation,\n  b: IndexRecommendation,\n): boolean {\n  // Must be same schema and table\n  if (a.schema !== b.schema || a.table !== b.table) return false;\n\n  // A must have more columns than B (not equal - that would be the same index)\n  if (a.columns.length <= b.columns.length) return false;\n\n  // B's columns must be a prefix of A's columns with matching sort\n  for (let i = 0; i < b.columns.length; i++) {\n    const colA = a.columns[i];\n    const colB = b.columns[i];\n\n    if (colA.column !== colB.column) return false;\n\n    // Sort directions must match\n    // Normalize: treat undefined/null as equivalent to default (ASC)\n    const sortA = normalizeSort(colA.sort);\n    const sortB = normalizeSort(colB.sort);\n    if (sortA !== sortB) return false;\n  }\n\n  // WHERE clause check: if B has a WHERE, A must have the same WHERE\n  if (b.where && a.where !== b.where) return false;\n\n  return true;\n}\n\nfunction normalizeSort(sort: unknown): string {\n  if (!sort) return \"ASC\";\n  if (typeof sort === \"string\") return sort.toUpperCase();\n  if (typeof sort === \"object\" && sort !== null && \"dir\" in sort) {\n    const dir = (sort as { dir?: string }).dir;\n    if (dir === \"SORTBY_DESC\") return \"DESC\";\n    return \"ASC\";\n  }\n  return \"ASC\";\n}\n\nexport interface IndexGroup {\n  /** The covering index (largest/most comprehensive) */\n  primary: AggregatedIndexRecommendation;\n  /** Indexes that are covered by the primary (prefixes of primary) */\n  covered: AggregatedIndexRecommendation[];\n}\n\n/**\n * Group indexes by coverage relationships.\n *\n * Returns groups where each group has a \"primary\" index that covers\n * zero or more \"covered\" indexes. Indexes that don't cover or aren't\n * covered by any other index become their own single-item group.\n */\nexport function groupIndexesByCoverage(\n  indexes: AggregatedIndexRecommendation[],\n): IndexGroup[] {\n  if (indexes.length === 0) return [];\n\n  // Track which indexes have been assigned to a group as \"covered\"\n  const coveredSet = new Set<string>();\n  const groups: IndexGroup[] = [];\n\n  // Sort by column count descending so we process larger indexes first\n  const sorted = [...indexes].sort(\n    (a, b) => b.index.columns.length - a.index.columns.length,\n  );\n\n  for (const idx of sorted) {\n    const key = idx.index.definition;\n\n    // Skip if already covered by another index\n    if (coveredSet.has(key)) continue;\n\n    // Find all indexes this one covers\n    const covered: AggregatedIndexRecommendation[] = [];\n    for (const other of sorted) {\n      if (other.index.definition === key) continue;\n      if (coveredSet.has(other.index.definition)) continue;\n\n      if (indexCovers(idx.index, other.index)) {\n        covered.push(other);\n        coveredSet.add(other.index.definition);\n      }\n    }\n\n    groups.push({\n      primary: idx,\n      covered,\n    });\n  }\n\n  return groups;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwBA,SAAgB,YACd,GACA,GACS;AAET,KAAI,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAO,QAAO;AAGzD,KAAI,EAAE,QAAQ,UAAU,EAAE,QAAQ,OAAQ,QAAO;AAGjD,MAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,QAAQ,KAAK;EACzC,MAAM,OAAO,EAAE,QAAQ;EACvB,MAAM,OAAO,EAAE,QAAQ;AAEvB,MAAI,KAAK,WAAW,KAAK,OAAQ,QAAO;AAMxC,MAFc,cAAc,KAAK,KAAK,KACxB,cAAc,KAAK,KAAK,CACjB,QAAO;;AAI9B,KAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAO,QAAO;AAE3C,QAAO;;AAGT,SAAS,cAAc,MAAuB;AAC5C,KAAI,CAAC,KAAM,QAAO;AAClB,KAAI,OAAO,SAAS,SAAU,QAAO,KAAK,aAAa;AACvD,KAAI,OAAO,SAAS,YAAY,SAAS,QAAQ,SAAS,MAAM;AAE9D,MADa,KAA0B,QAC3B,cAAe,QAAO;AAClC,SAAO;;AAET,QAAO;;;;;;;;;AAiBT,SAAgB,uBACd,SACc;AACd,KAAI,QAAQ,WAAW,EAAG,QAAO,EAAE;CAGnC,MAAM,6BAAa,IAAI,KAAa;CACpC,MAAM,SAAuB,EAAE;CAG/B,MAAM,SAAS,CAAC,GAAG,QAAQ,CAAC,MACzB,GAAG,MAAM,EAAE,MAAM,QAAQ,SAAS,EAAE,MAAM,QAAQ,OACpD;AAED,MAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,MAAM,IAAI,MAAM;AAGtB,MAAI,WAAW,IAAI,IAAI,CAAE;EAGzB,MAAM,UAA2C,EAAE;AACnD,OAAK,MAAM,SAAS,QAAQ;AAC1B,OAAI,MAAM,MAAM,eAAe,IAAK;AACpC,OAAI,WAAW,IAAI,MAAM,MAAM,WAAW,CAAE;AAE5C,OAAI,YAAY,IAAI,OAAO,MAAM,MAAM,EAAE;AACvC,YAAQ,KAAK,MAAM;AACnB,eAAW,IAAI,MAAM,MAAM,WAAW;;;AAI1C,SAAO,KAAK;GACV,SAAS;GACT;GACD,CAAC;;AAGJ,QAAO"}

package/dist/action-plan/index-coverage.d.cts

@@ -0,0 +1,44 @@
+'use client';
+
+import { IndexRecommendation } from "../query.cjs";
+
+//#region src/action-plan/index-coverage.d.ts
+/** A unique index recommendation plus how it scored across the queries it helps. */
+interface AggregatedIndexRecommendation {
+  index: IndexRecommendation;
+  affectedQueryCount: number;
+  averageCostReduction: number;
+  bestCostReduction: number;
+  affectedQueryHashes: string[];
+}
+/**
+ * Check if indexA covers indexB (A is a superset that includes B as a prefix).
+ *
+ * Rules:
+ * - Same schema and table
+ * - A's columns start with B's columns (B is a prefix of A)
+ * - Sort directions must match for prefix columns
+ * - WHERE clauses must be compatible
+ *
+ * Examples:
+ * - (a, b, c) covers (a, b) and (a)
+ * - (a DESC, b) covers (a DESC) but NOT (a ASC)
+ */
+declare function indexCovers(a: IndexRecommendation, b: IndexRecommendation): boolean;
+interface IndexGroup {
+  /** The covering index (largest/most comprehensive) */
+  primary: AggregatedIndexRecommendation;
+  /** Indexes that are covered by the primary (prefixes of primary) */
+  covered: AggregatedIndexRecommendation[];
+}
+/**
+ * Group indexes by coverage relationships.
+ *
+ * Returns groups where each group has a "primary" index that covers
+ * zero or more "covered" indexes. Indexes that don't cover or aren't
+ * covered by any other index become their own single-item group.
+ */
+declare function groupIndexesByCoverage(indexes: AggregatedIndexRecommendation[]): IndexGroup[];
+//#endregion
+export { AggregatedIndexRecommendation, IndexGroup, groupIndexesByCoverage, indexCovers };
+//# sourceMappingURL=index-coverage.d.cts.map

package/dist/action-plan/index-coverage.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-coverage.d.cts","names":[],"sources":["../../src/action-plan/index-coverage.ts"],"mappings":";;;;;;UAGiB,6BAAA;EACf,KAAA,EAAO,mBAAA;EACP,kBAAA;EACA,oBAAA;EACA,iBAAA;EACA,mBAAA;AAAA;;;;;;;;AAgBF;;;;;;iBAAgB,WAAA,CACd,CAAA,EAAG,mBAAA,EACH,CAAA,EAAG,mBAAA;AAAA,UAuCY,UAAA;EAvCO;EAyCtB,OAAA,EAAS,6BAAA;EAFM;EAIf,OAAA,EAAS,6BAAA;AAAA;;;;;;;;iBAUK,sBAAA,CACd,OAAA,EAAS,6BAAA,KACR,UAAA"}

package/dist/action-plan/index-coverage.d.mts

@@ -0,0 +1,44 @@
+'use client';
+
+import { IndexRecommendation } from "../query.mjs";
+
+//#region src/action-plan/index-coverage.d.ts
+/** A unique index recommendation plus how it scored across the queries it helps. */
+interface AggregatedIndexRecommendation {
+  index: IndexRecommendation;
+  affectedQueryCount: number;
+  averageCostReduction: number;
+  bestCostReduction: number;
+  affectedQueryHashes: string[];
+}
+/**
+ * Check if indexA covers indexB (A is a superset that includes B as a prefix).
+ *
+ * Rules:
+ * - Same schema and table
+ * - A's columns start with B's columns (B is a prefix of A)
+ * - Sort directions must match for prefix columns
+ * - WHERE clauses must be compatible
+ *
+ * Examples:
+ * - (a, b, c) covers (a, b) and (a)
+ * - (a DESC, b) covers (a DESC) but NOT (a ASC)
+ */
+declare function indexCovers(a: IndexRecommendation, b: IndexRecommendation): boolean;
+interface IndexGroup {
+  /** The covering index (largest/most comprehensive) */
+  primary: AggregatedIndexRecommendation;
+  /** Indexes that are covered by the primary (prefixes of primary) */
+  covered: AggregatedIndexRecommendation[];
+}
+/**
+ * Group indexes by coverage relationships.
+ *
+ * Returns groups where each group has a "primary" index that covers
+ * zero or more "covered" indexes. Indexes that don't cover or aren't
+ * covered by any other index become their own single-item group.
+ */
+declare function groupIndexesByCoverage(indexes: AggregatedIndexRecommendation[]): IndexGroup[];
+//#endregion
+export { AggregatedIndexRecommendation, IndexGroup, groupIndexesByCoverage, indexCovers };
+//# sourceMappingURL=index-coverage.d.mts.map

package/dist/action-plan/index-coverage.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-coverage.d.mts","names":[],"sources":["../../src/action-plan/index-coverage.ts"],"mappings":";;;;;;UAGiB,6BAAA;EACf,KAAA,EAAO,mBAAA;EACP,kBAAA;EACA,oBAAA;EACA,iBAAA;EACA,mBAAA;AAAA;;;;;;;;AAgBF;;;;;;iBAAgB,WAAA,CACd,CAAA,EAAG,mBAAA,EACH,CAAA,EAAG,mBAAA;AAAA,UAuCY,UAAA;EAvCO;EAyCtB,OAAA,EAAS,6BAAA;EAFM;EAIf,OAAA,EAAS,6BAAA;AAAA;;;;;;;;iBAUK,sBAAA,CACd,OAAA,EAAS,6BAAA,KACR,UAAA"}

package/dist/action-plan/index-coverage.mjs

@@ -0,0 +1,71 @@
+"use client";
+//#region src/action-plan/index-coverage.ts
+/**
+* Check if indexA covers indexB (A is a superset that includes B as a prefix).
+*
+* Rules:
+* - Same schema and table
+* - A's columns start with B's columns (B is a prefix of A)
+* - Sort directions must match for prefix columns
+* - WHERE clauses must be compatible
+*
+* Examples:
+* - (a, b, c) covers (a, b) and (a)
+* - (a DESC, b) covers (a DESC) but NOT (a ASC)
+*/
+function indexCovers(a, b) {
+	if (a.schema !== b.schema || a.table !== b.table) return false;
+	if (a.columns.length <= b.columns.length) return false;
+	for (let i = 0; i < b.columns.length; i++) {
+		const colA = a.columns[i];
+		const colB = b.columns[i];
+		if (colA.column !== colB.column) return false;
+		if (normalizeSort(colA.sort) !== normalizeSort(colB.sort)) return false;
+	}
+	if (b.where && a.where !== b.where) return false;
+	return true;
+}
+function normalizeSort(sort) {
+	if (!sort) return "ASC";
+	if (typeof sort === "string") return sort.toUpperCase();
+	if (typeof sort === "object" && sort !== null && "dir" in sort) {
+		if (sort.dir === "SORTBY_DESC") return "DESC";
+		return "ASC";
+	}
+	return "ASC";
+}
+/**
+* Group indexes by coverage relationships.
+*
+* Returns groups where each group has a "primary" index that covers
+* zero or more "covered" indexes. Indexes that don't cover or aren't
+* covered by any other index become their own single-item group.
+*/
+function groupIndexesByCoverage(indexes) {
+	if (indexes.length === 0) return [];
+	const coveredSet = /* @__PURE__ */ new Set();
+	const groups = [];
+	const sorted = [...indexes].sort((a, b) => b.index.columns.length - a.index.columns.length);
+	for (const idx of sorted) {
+		const key = idx.index.definition;
+		if (coveredSet.has(key)) continue;
+		const covered = [];
+		for (const other of sorted) {
+			if (other.index.definition === key) continue;
+			if (coveredSet.has(other.index.definition)) continue;
+			if (indexCovers(idx.index, other.index)) {
+				covered.push(other);
+				coveredSet.add(other.index.definition);
+			}
+		}
+		groups.push({
+			primary: idx,
+			covered
+		});
+	}
+	return groups;
+}
+//#endregion
+export { groupIndexesByCoverage, indexCovers };
+
+//# sourceMappingURL=index-coverage.mjs.map

package/dist/action-plan/index-coverage.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-coverage.mjs","names":[],"sources":["../../src/action-plan/index-coverage.ts"],"sourcesContent":["import type { IndexRecommendation } from \"../query.js\";\n\n/** A unique index recommendation plus how it scored across the queries it helps. */\nexport interface AggregatedIndexRecommendation {\n  index: IndexRecommendation;\n  affectedQueryCount: number;\n  averageCostReduction: number;\n  bestCostReduction: number;\n  affectedQueryHashes: string[];\n}\n\n/**\n * Check if indexA covers indexB (A is a superset that includes B as a prefix).\n *\n * Rules:\n * - Same schema and table\n * - A's columns start with B's columns (B is a prefix of A)\n * - Sort directions must match for prefix columns\n * - WHERE clauses must be compatible\n *\n * Examples:\n * - (a, b, c) covers (a, b) and (a)\n * - (a DESC, b) covers (a DESC) but NOT (a ASC)\n */\nexport function indexCovers(\n  a: IndexRecommendation,\n  b: IndexRecommendation,\n): boolean {\n  // Must be same schema and table\n  if (a.schema !== b.schema || a.table !== b.table) return false;\n\n  // A must have more columns than B (not equal - that would be the same index)\n  if (a.columns.length <= b.columns.length) return false;\n\n  // B's columns must be a prefix of A's columns with matching sort\n  for (let i = 0; i < b.columns.length; i++) {\n    const colA = a.columns[i];\n    const colB = b.columns[i];\n\n    if (colA.column !== colB.column) return false;\n\n    // Sort directions must match\n    // Normalize: treat undefined/null as equivalent to default (ASC)\n    const sortA = normalizeSort(colA.sort);\n    const sortB = normalizeSort(colB.sort);\n    if (sortA !== sortB) return false;\n  }\n\n  // WHERE clause check: if B has a WHERE, A must have the same WHERE\n  if (b.where && a.where !== b.where) return false;\n\n  return true;\n}\n\nfunction normalizeSort(sort: unknown): string {\n  if (!sort) return \"ASC\";\n  if (typeof sort === \"string\") return sort.toUpperCase();\n  if (typeof sort === \"object\" && sort !== null && \"dir\" in sort) {\n    const dir = (sort as { dir?: string }).dir;\n    if (dir === \"SORTBY_DESC\") return \"DESC\";\n    return \"ASC\";\n  }\n  return \"ASC\";\n}\n\nexport interface IndexGroup {\n  /** The covering index (largest/most comprehensive) */\n  primary: AggregatedIndexRecommendation;\n  /** Indexes that are covered by the primary (prefixes of primary) */\n  covered: AggregatedIndexRecommendation[];\n}\n\n/**\n * Group indexes by coverage relationships.\n *\n * Returns groups where each group has a \"primary\" index that covers\n * zero or more \"covered\" indexes. Indexes that don't cover or aren't\n * covered by any other index become their own single-item group.\n */\nexport function groupIndexesByCoverage(\n  indexes: AggregatedIndexRecommendation[],\n): IndexGroup[] {\n  if (indexes.length === 0) return [];\n\n  // Track which indexes have been assigned to a group as \"covered\"\n  const coveredSet = new Set<string>();\n  const groups: IndexGroup[] = [];\n\n  // Sort by column count descending so we process larger indexes first\n  const sorted = [...indexes].sort(\n    (a, b) => b.index.columns.length - a.index.columns.length,\n  );\n\n  for (const idx of sorted) {\n    const key = idx.index.definition;\n\n    // Skip if already covered by another index\n    if (coveredSet.has(key)) continue;\n\n    // Find all indexes this one covers\n    const covered: AggregatedIndexRecommendation[] = [];\n    for (const other of sorted) {\n      if (other.index.definition === key) continue;\n      if (coveredSet.has(other.index.definition)) continue;\n\n      if (indexCovers(idx.index, other.index)) {\n        covered.push(other);\n        coveredSet.add(other.index.definition);\n      }\n    }\n\n    groups.push({\n      primary: idx,\n      covered,\n    });\n  }\n\n  return groups;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwBA,SAAgB,YACd,GACA,GACS;AAET,KAAI,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAO,QAAO;AAGzD,KAAI,EAAE,QAAQ,UAAU,EAAE,QAAQ,OAAQ,QAAO;AAGjD,MAAK,IAAI,IAAI,GAAG,IAAI,EAAE,QAAQ,QAAQ,KAAK;EACzC,MAAM,OAAO,EAAE,QAAQ;EACvB,MAAM,OAAO,EAAE,QAAQ;AAEvB,MAAI,KAAK,WAAW,KAAK,OAAQ,QAAO;AAMxC,MAFc,cAAc,KAAK,KAAK,KACxB,cAAc,KAAK,KAAK,CACjB,QAAO;;AAI9B,KAAI,EAAE,SAAS,EAAE,UAAU,EAAE,MAAO,QAAO;AAE3C,QAAO;;AAGT,SAAS,cAAc,MAAuB;AAC5C,KAAI,CAAC,KAAM,QAAO;AAClB,KAAI,OAAO,SAAS,SAAU,QAAO,KAAK,aAAa;AACvD,KAAI,OAAO,SAAS,YAAY,SAAS,QAAQ,SAAS,MAAM;AAE9D,MADa,KAA0B,QAC3B,cAAe,QAAO;AAClC,SAAO;;AAET,QAAO;;;;;;;;;AAiBT,SAAgB,uBACd,SACc;AACd,KAAI,QAAQ,WAAW,EAAG,QAAO,EAAE;CAGnC,MAAM,6BAAa,IAAI,KAAa;CACpC,MAAM,SAAuB,EAAE;CAG/B,MAAM,SAAS,CAAC,GAAG,QAAQ,CAAC,MACzB,GAAG,MAAM,EAAE,MAAM,QAAQ,SAAS,EAAE,MAAM,QAAQ,OACpD;AAED,MAAK,MAAM,OAAO,QAAQ;EACxB,MAAM,MAAM,IAAI,MAAM;AAGtB,MAAI,WAAW,IAAI,IAAI,CAAE;EAGzB,MAAM,UAA2C,EAAE;AACnD,OAAK,MAAM,SAAS,QAAQ;AAC1B,OAAI,MAAM,MAAM,eAAe,IAAK;AACpC,OAAI,WAAW,IAAI,MAAM,MAAM,WAAW,CAAE;AAE5C,OAAI,YAAY,IAAI,OAAO,MAAM,MAAM,EAAE;AACvC,YAAQ,KAAK,MAAM;AACnB,eAAW,IAAI,MAAM,MAAM,WAAW;;;AAI1C,SAAO,KAAK;GACV,SAAS;GACT;GACD,CAAC;;AAGJ,QAAO"}

package/dist/index.cjs

@@ -12,6 +12,9 @@ const require_genalgo = require("./optimizer/genalgo.cjs");
 const require_statistics = require("./optimizer/statistics.cjs");
 const require_dump = require("./optimizer/dump.cjs");
 const require_pss_rewriter = require("./optimizer/pss-rewriter.cjs");
+const require_index_coverage = require("./action-plan/index-coverage.cjs");
+const require_aggregate_index_recommendations = require("./action-plan/aggregate-index-recommendations.cjs");
+const require_build_action_plan = require("./action-plan/build-action-plan.cjs");
 const require_sentry = require("./sentry.cjs");
 const require_query = require("./query.cjs");
 exports.Analyzer = require_analyzer.Analyzer;
@@ -53,6 +56,8 @@ exports.SKIP = require_genalgo.SKIP;
 exports.Statistics = require_statistics.Statistics;
 exports.StatisticsMode = require_statistics.StatisticsMode;
 exports.StatisticsSource = require_statistics.StatisticsSource;
+exports.aggregateIndexRecommendations = require_aggregate_index_recommendations.aggregateIndexRecommendations;
+exports.buildActionPlan = require_build_action_plan.buildActionPlan;
 exports.combinedDumpSql = require_dump.combinedDumpSql;
 exports.compactSelectList = require_display_query.compactSelectList;
 exports.deriveSentryEnvironment = require_sentry.deriveSentryEnvironment;
@@ -60,7 +65,9 @@ exports.dropIndex = require_database.dropIndex;
 exports.dumpQueriesSql = require_dump.dumpQueriesSql;
 exports.dumpSchema = require_schema.dumpSchema;
 exports.groupDuplicateIndexes = require_indexes.groupDuplicateIndexes;
+exports.groupIndexesByCoverage = require_index_coverage.groupIndexesByCoverage;
 exports.ignoredIdentifier = require_analyzer.ignoredIdentifier;
+exports.indexCovers = require_index_coverage.indexCovers;
 exports.isIndexProbablyDroppable = require_indexes.isIndexProbablyDroppable;
 exports.isIndexSupported = require_indexes.isIndexSupported;
 exports.parseNudges = require_nudges.parseNudges;