turbine-orm 0.46.0 → 0.47.0

package/dist/cjs/cli/index.js

@@ -15,7 +15,7 @@
  *   turbine migrate status        — Show migration status
  *   turbine seed                  — Run seed file
  *   turbine status                — Show schema summary
- *   turbine doctor                - Cost-aware missing-FK-index triage (--fix, --json, --no-concurrently)
+ *   turbine doctor                - Cost-aware missing-FK-index triage (--fix, --json, --no-concurrently, --unused, --audit)
  *   turbine studio                : Launch local read-only web UI (--demo for a seeded sample DB)
  *   turbine mcp                   — Start read-only MCP server over JSON-RPC stdio
  *   turbine observe               — Launch metrics dashboard (requires TURBINE_OBSERVE_URL)
@@ -171,6 +171,20 @@ function parseArgs(argv = process.argv.slice(2)) {
             case '--no-concurrently':
                 result.noConcurrently = true;
                 break;
+            case '--unused':
+                result.unused = true;
+                break;
+            case '--audit':
+                result.audit = true;
+                break;
+            case '--min-scans':
+                result.minScans = next ? Number.parseInt(next, 10) : undefined;
+                i++;
+                break;
+            case '--metrics-url':
+                result.metricsUrl = next;
+                i++;
+                break;
             case '--zod':
                 result.zod = true;
                 break;
@@ -2138,20 +2152,64 @@ async function cmdDoctor(args, config) {
             notices: [`statistics collection failed: ${err instanceof Error ? err.message : String(err)}`],
         };
     }
+    // Table-heat boost: read _turbine_metrics (app DB or --metrics-url) and use
+    // per-model heat as an extra benefit signal. Best-effort; a missing table just
+    // means "heat boosting unavailable" and the triage continues without it.
+    const heat = probedTables.length > 0
+        ? await collectTableHeatSafe(args.metricsUrl ?? url, probedTables)
+        : { available: false, tables: {}, notice: null };
     const invalid = (0, index_stats_js_1.findInvalidIndexes)(snapshot);
     const usable = (0, index_stats_js_1.isSnapshotUsable)(snapshot);
-    const findings = missing.map((m) => ({ missing: m, score: (0, index_stats_js_1.scoreMissingIndex)(m, snapshot) }));
+    const findings = missing.map((m) => ({
+        missing: m,
+        score: (0, index_stats_js_1.scoreMissingIndex)(m, snapshot, heat.tables[m.table]),
+    }));
+    // "doctor learns to subtract": report-only drop suggestions, never a migration.
+    const unusedRan = args.unused === true;
+    const auditRan = args.audit === true;
+    const minScans = args.minScans;
+    const unused = unusedRan ? (0, index_stats_js_1.findUnusedIndexes)(snapshot, { minScans }) : [];
+    const redundant = unusedRan ? (0, index_stats_js_1.findRedundantIndexes)(snapshot) : [];
+    const audit = auditRan ? (0, index_stats_js_1.auditDoctorIndexes)(snapshot, (0, index_advisor_js_1.collectDoctorProbeIndexNames)(schema), { minScans }) : [];
+    const subtract = { unusedRan, auditRan, minScans, unused, redundant, audit };
     if (jsonMode) {
         spinner?.stop();
-        console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, args }), null, 2));
+        console.log(JSON.stringify(buildDoctorJson({ schema, findings, invalid, snapshot, usable, heat, subtract, args }), null, 2));
         return;
     }
-    await renderDoctorHuman({ spinner: spinner, schema, findings, invalid, snapshot, usable, args, config });
+    await renderDoctorHuman({
+        spinner: spinner,
+        schema,
+        findings,
+        invalid,
+        snapshot,
+        usable,
+        heat,
+        subtract,
+        args,
+        config,
+    });
+}
+/** Best-effort table-heat read: any failure degrades to unavailable, never throws. */
+async function collectTableHeatSafe(connectionString, models) {
+    try {
+        return await (0, index_stats_js_1.collectTableHeat)({ connectionString, models });
+    }
+    catch (err) {
+        return {
+            available: false,
+            tables: {},
+            notice: `heat boosting is unavailable (reading _turbine_metrics failed: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}).`,
+        };
+    }
 }
-/** The stable, versioned JSON contract (schemaVersion: 1). First external consumer: BataDB import. */
+/**
+ * The stable, versioned JSON contract (schemaVersion: 1). Fields are only ever
+ * added, never removed or repurposed, so a parser never breaks on an upgrade.
+ */
 function buildDoctorJson(ctx) {
     const concurrently = ctx.args.noConcurrently !== true;
-    return {
+    const out = {
         schemaVersion: 1,
         scannedTables: Object.keys(ctx.schema.tables).length,
         stats: {
@@ -2161,6 +2219,10 @@ function buildDoctorJson(ctx) {
             statsAgeDays: ctx.snapshot.statsAgeDays,
             notices: ctx.snapshot.notices,
         },
+        heat: {
+            available: ctx.heat.available,
+            notice: ctx.heat.notice,
+        },
         thresholds: index_stats_js_1.STATS_THRESHOLDS,
         findings: ctx.findings.map((f) => ({
             table: f.missing.table,
@@ -2171,18 +2233,37 @@ function buildDoctorJson(ctx) {
             metrics: f.score.metrics,
             hotWarning: f.score.hotWarning,
             partialNotNull: f.score.partialNotNull,
+            heatBoosted: f.score.heatBoosted,
             probes: f.missing.probes,
             createSql: doctorCreateSql(f, { concurrently }),
             dropSql: (0, index_advisor_js_1.buildDropIndexSql)(f.missing.indexName, { concurrently }),
         })),
         invalidIndexes: ctx.invalid,
     };
+    // Additive: the drop-suggestion arrays appear only when --unused / --audit ran.
+    if (ctx.subtract.unusedRan) {
+        out.unused = ctx.subtract.unused;
+        out.redundant = ctx.subtract.redundant;
+        out.invalid = ctx.invalid;
+    }
+    if (ctx.subtract.auditRan) {
+        out.audit = ctx.subtract.audit;
+    }
+    return out;
 }
 async function renderDoctorHuman(ctx) {
-    const { spinner, schema, findings, invalid, snapshot, usable, args, config } = ctx;
+    const { spinner, schema, findings, invalid, snapshot, usable, heat, subtract, args, config } = ctx;
     spinner.succeed(`Scanned ${(0, ui_js_1.bold)(String(Object.keys(schema.tables).length))} tables`);
-    if (findings.length === 0 && invalid.length === 0) {
-        (0, ui_js_1.success)('Every relation probe is backed by an index, and no invalid indexes were found');
+    const subtractRan = subtract.unusedRan || subtract.auditRan;
+    const nothingToAdd = findings.length === 0 && invalid.length === 0;
+    const nothingToSubtract = subtract.unused.length === 0 && subtract.redundant.length === 0 && subtract.audit.length === 0;
+    if (nothingToAdd && (!subtractRan || nothingToSubtract)) {
+        if (subtractRan) {
+            (0, ui_js_1.success)('No never-scanned or redundant indexes found, and no invalid indexes were found');
+        }
+        else {
+            (0, ui_js_1.success)('Every relation probe is backed by an index, and no invalid indexes were found');
+        }
         (0, ui_js_1.newline)();
         return;
     }
@@ -2198,8 +2279,20 @@ async function renderDoctorHuman(ctx) {
         else {
             renderTopologyFallback(findings, snapshot);
         }
+        // Heat honesty: one line when the workload-heat boost could not be sourced.
+        if (!heat.available && heat.notice) {
+            console.log(`  ${(0, ui_js_1.dim)(`Note: ${heat.notice}`)}`);
+            (0, ui_js_1.newline)();
+        }
     }
     renderInvalidIndexes(invalid);
+    if (subtract.unusedRan) {
+        renderUnusedIndexes(subtract.unused, subtract.minScans, snapshot);
+        renderRedundantIndexes(subtract.redundant);
+    }
+    if (subtract.auditRan) {
+        renderDoctorAudit(subtract.audit, subtract.minScans, snapshot);
+    }
     if (findings.length > 0) {
         if (args.fix) {
             renderFixMigration(findings, config, args);
@@ -2211,6 +2304,65 @@ async function renderDoctorHuman(ctx) {
         }
     }
 }
+/** Shared caveat block: what an idx_scan of zero does and does not prove. */
+function renderUnusedCaveats(minScans, snapshot) {
+    const ageLabel = snapshot.statsAgeDays !== null ? `${Math.round(snapshot.statsAgeDays)}d` : 'unknown';
+    const threshold = minScans ?? index_stats_js_1.STATS_THRESHOLDS.unusedMinScans;
+    console.log(`  ${(0, ui_js_1.dim)(`Usage counters are since the last stats reset (${ageLabel} ago).`)}`);
+    console.log(`  ${(0, ui_js_1.dim)(`Caveats: counters zero on a stats reset or crash; a read replica's index scans NEVER feed`)}`);
+    console.log(`  ${(0, ui_js_1.dim)(`the primary's counters, so an index only a replica uses looks dead here. Threshold: idx_scan < ${threshold}.`)}`);
+    console.log(`  ${(0, ui_js_1.dim)('Primary-key, unique, exclusion, and replica-identity indexes are excluded. Nothing here is auto-dropped.')}`);
+    (0, ui_js_1.newline)();
+}
+/** doctor --unused: never-scanned indexes with DROP suggestions (report-only). */
+function renderUnusedIndexes(unused, minScans, snapshot) {
+    if (unused.length === 0)
+        return;
+    const total = unused.reduce((sum, u) => sum + (u.sizeBytes ?? 0), 0);
+    (0, ui_js_1.warn)(`Found ${(0, ui_js_1.bold)(String(unused.length))} never-scanned index(es) (${(0, index_stats_js_1.formatBytes)(total)} reclaimable).`);
+    renderUnusedCaveats(minScans, snapshot);
+    for (const u of unused) {
+        console.log(`  ${(0, ui_js_1.yellow)(ui_js_1.symbols.warning)} ${(0, ui_js_1.bold)((0, ui_js_1.cyan)(u.table))} ${(0, ui_js_1.dim)(`(${u.columns.join(', ') || '?'})`)}  ${(0, ui_js_1.gray)(`${u.indexName} · ${u.idxScan} scans · ${(0, index_stats_js_1.formatBytes)(u.sizeBytes)}`)}`);
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(u.dropSql)}`);
+        (0, ui_js_1.newline)();
+    }
+}
+/** doctor --unused: redundant leading-prefix indexes with DROP suggestions (report-only). */
+function renderRedundantIndexes(redundant) {
+    if (redundant.length === 0)
+        return;
+    const total = redundant.reduce((sum, r) => sum + (r.sizeBytes ?? 0), 0);
+    (0, ui_js_1.warn)(`Found ${(0, ui_js_1.bold)(String(redundant.length))} redundant index(es) (${(0, index_stats_js_1.formatBytes)(total)} reclaimable).`);
+    console.log(`  ${(0, ui_js_1.dim)('Each is a leading prefix of a wider index that already serves the same lookups. Report-only, never auto-dropped.')}`);
+    (0, ui_js_1.newline)();
+    for (const r of redundant) {
+        console.log(`  ${(0, ui_js_1.yellow)(ui_js_1.symbols.warning)} ${(0, ui_js_1.bold)((0, ui_js_1.cyan)(r.table))} ${(0, ui_js_1.dim)(`(${r.columns.join(', ')})`)}  ${(0, ui_js_1.gray)(`${r.indexName} · ${(0, index_stats_js_1.formatBytes)(r.sizeBytes)}`)}`);
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} covered by ${(0, ui_js_1.blue)(r.coveredBy)} ${(0, ui_js_1.dim)(`(${r.coveredByColumns.join(', ')})`)}`);
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(r.dropSql)}`);
+        (0, ui_js_1.newline)();
+    }
+}
+/** doctor --audit: doctor's own previously-suggested indexes now never scanned. */
+function renderDoctorAudit(audit, minScans, snapshot) {
+    if (audit.length === 0) {
+        (0, ui_js_1.success)('No doctor-suggested index is going unused');
+        (0, ui_js_1.newline)();
+        return;
+    }
+    (0, ui_js_1.warn)(`doctor previously suggested these indexes; ${(0, ui_js_1.bold)(String(audit.length))} have never been scanned since the stats reset.`);
+    renderUnusedCaveats(minScans, snapshot);
+    for (const a of audit) {
+        const tag = a.ambiguous ? (0, ui_js_1.red)(' [ambiguous: truncated name collides with another column set]') : '';
+        console.log(`  ${(0, ui_js_1.yellow)(ui_js_1.symbols.warning)} ${(0, ui_js_1.bold)((0, ui_js_1.cyan)(a.table))} ${(0, ui_js_1.dim)(`(${a.columns.join(', ') || '?'})`)}  ${(0, ui_js_1.gray)(`${a.indexName} · ${a.idxScan} scans · ${(0, index_stats_js_1.formatBytes)(a.sizeBytes)}`)}${tag}`);
+        if (a.ambiguous) {
+            console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.tee)} ${(0, ui_js_1.dim)('the 63-byte name maps to more than one probe column set; confirm before dropping')}`);
+        }
+        console.log(`    ${(0, ui_js_1.dim)(ui_js_1.symbols.teeEnd)} ${(0, ui_js_1.green)(a.dropSql)}`);
+        (0, ui_js_1.newline)();
+    }
+    console.log(`  ${(0, ui_js_1.dim)('Consider dropping the ones you confirm are unused. Nothing here is auto-dropped.')}`);
+    (0, ui_js_1.newline)();
+}
 /** Cost-aware tiered output: three sections, each finding annotated with its numbers. */
 function renderTiers(findings, snapshot, _args) {
     const ageLabel = snapshot.statsAgeDays !== null ? `${Math.round(snapshot.statsAgeDays)}d` : 'unknown';
@@ -2735,7 +2887,7 @@ function showHelp() {
     console.log(`      ${(0, ui_js_1.dim)('status')}           Show applied/pending migrations`);
     console.log(`    ${(0, ui_js_1.cyan)('seed')}               Run seed file`);
     console.log(`    ${(0, ui_js_1.cyan)('status')} ${(0, ui_js_1.dim)('| info')}      Show schema summary`);
-    console.log(`    ${(0, ui_js_1.cyan)('doctor')}             Cost-aware missing-FK-index triage ${(0, ui_js_1.dim)('(--fix, --json, --no-concurrently)')}`);
+    console.log(`    ${(0, ui_js_1.cyan)('doctor')}             Cost-aware missing-FK-index triage ${(0, ui_js_1.dim)('(--fix, --json, --unused, --audit)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('studio')}             Launch local read-only web UI ${(0, ui_js_1.dim)('(--write for writes, --demo for a sample DB)')}`);
     console.log(`    ${(0, ui_js_1.cyan)('mcp')}                Start read-only MCP server over stdio`);
     console.log(`    ${(0, ui_js_1.cyan)('observe')}            Launch metrics dashboard ${(0, ui_js_1.dim)('(requires TURBINE_OBSERVE_URL)')}`);

package/dist/cjs/index-stats.js

@@ -65,8 +65,12 @@ exports.emptyStatsSnapshot = emptyStatsSnapshot;
 exports.formatBytes = formatBytes;
 exports.scoreMissingIndex = scoreMissingIndex;
 exports.findInvalidIndexes = findInvalidIndexes;
+exports.findUnusedIndexes = findUnusedIndexes;
+exports.findRedundantIndexes = findRedundantIndexes;
+exports.auditDoctorIndexes = auditDoctorIndexes;
 exports.isSnapshotUsable = isSnapshotUsable;
 exports.collectStatsSnapshot = collectStatsSnapshot;
+exports.collectTableHeat = collectTableHeat;
 const index_advisor_js_1 = require("./index-advisor.js");
 // ---------------------------------------------------------------------------
 // Thresholds (exported + printed so a user can see exactly why a tier was chosen)
@@ -114,6 +118,18 @@ exports.STATS_THRESHOLDS = {
     appendHeavyInsertRatio: 0.95,
     /** ... and seq_scan at or below this ("near-zero probe reads") → scrutinize. */
     appendHeavyMaxSeqScan: 5,
+    /**
+     * Default `--min-scans` for the unused-index report: an index with fewer than
+     * this many scans since stats_reset is flagged never-scanned. Default 1 makes
+     * the bare report mean exactly "idx_scan = 0".
+     */
+    unusedMinScans: 1,
+    /**
+     * Queries/min (from _turbine_metrics) at or above this makes a table "hot in
+     * your workload": a benefit signal that boosts the finding's priority and
+     * annotates it. It never downgrades a cost tier (write cost is a separate axis).
+     */
+    heatMinQueriesPerMin: 1,
 };
 /** Build an empty (fully unavailable) snapshot - the honest "no stats" baseline. */
 function emptyStatsSnapshot(notices = []) {
@@ -149,7 +165,7 @@ function formatInt(n) {
  * Score a single missing-index finding against a snapshot. Pure and total:
  * every unknown degrades to a caveat rather than a fabricated number.
  */
-function scoreMissingIndex(missing, snapshot) {
+function scoreMissingIndex(missing, snapshot, heat) {
     const t = exports.STATS_THRESHOLDS;
     const stats = snapshot.tables[missing.table];
     const probingRelations = missing.probes.length;
@@ -261,8 +277,17 @@ function scoreMissingIndex(missing, snapshot) {
     if (partialNotNull) {
         reasons.push(`column is ${Math.round((nullFrac ?? 0) * 100)}% NULL: suggesting a partial "WHERE ${missing.columns[0]} IS NOT NULL" index (caveat: a user-written where: { ${missing.columns[0]}: null } filter will NOT use it)`);
     }
+    // Workload heat is a BENEFIT signal, not a cost one: a table your app hits hard
+    // is a table where a missing index hurts most. It never downgrades a cost tier
+    // (write cost is decided above); it re-prioritizes and annotates.
+    const heatBoosted = heat !== undefined && heat.queriesPerMin >= t.heatMinQueriesPerMin;
+    if (heatBoosted && heat !== undefined) {
+        reasons.push(`hot in your workload: ${formatInt(heat.queriesPerMin)} queries/min, p95 ${heat.p95Ms >= 10 ? Math.round(heat.p95Ms) : heat.p95Ms.toFixed(1)} ms`);
+    }
     // Benefit sort key: bigger, more-probed tables first. Unknown rows sort last.
-    const benefitScore = (rows ?? 0) * Math.max(1, probingRelations);
+    // A heat-boosted finding is lifted above every non-hot finding in its tier.
+    const base = (rows ?? 0) * Math.max(1, probingRelations);
+    const benefitScore = heatBoosted && heat !== undefined ? base + (heat.queriesPerMin + 1) * 1e12 : base;
     return {
         table: missing.table,
         columns: missing.columns,
@@ -271,6 +296,7 @@ function scoreMissingIndex(missing, snapshot) {
         metrics,
         hotWarning,
         partialNotNull,
+        heatBoosted,
         benefitScore,
     };
 }
@@ -297,6 +323,123 @@ function findInvalidIndexes(snapshot) {
     }))
         .sort((a, b) => a.indexName.localeCompare(b.indexName));
 }
+// ---------------------------------------------------------------------------
+// Unused-index detection (pure): doctor learns to subtract
+// ---------------------------------------------------------------------------
+/**
+ * An index constraint-backing indexes are NEVER candidates for a drop suggestion:
+ * a primary key, a unique constraint, or an exclusion constraint owns its index,
+ * and a replica-identity index is load-bearing for logical replication. Dropping
+ * any of these changes semantics, not just performance.
+ */
+function isConstraintBacking(idx) {
+    return idx.isPrimary || idx.isUnique || idx.isExclusion === true || idx.isReplicaIdent;
+}
+/**
+ * Indexes never (or barely) scanned since the last stats reset. Report-only:
+ * counters reset on a crash/reset and REPLICA READS NEVER FEED PRIMARY COUNTERS,
+ * so an index only a read replica uses looks dead here. Constraint-backing and
+ * replica-identity indexes are excluded by construction. An index whose idx_scan
+ * could not be read (no pg_stat row) is skipped rather than guessed.
+ */
+function findUnusedIndexes(snapshot, options = {}) {
+    const minScans = options.minScans ?? exports.STATS_THRESHOLDS.unusedMinScans;
+    return snapshot.indexes
+        .filter((idx) => idx.isValid && !isConstraintBacking(idx))
+        .filter((idx) => idx.idxScan !== undefined && idx.idxScan < minScans)
+        .map((idx) => ({
+        table: idx.table,
+        indexName: idx.indexName,
+        columns: idx.columns,
+        idxScan: idx.idxScan ?? 0,
+        sizeBytes: idx.sizeBytes ?? null,
+        dropSql: (0, index_advisor_js_1.buildDropIndexSql)(idx.indexName, { concurrently: true }),
+    }))
+        .sort((a, b) => (b.sizeBytes ?? 0) - (a.sizeBytes ?? 0) || a.indexName.localeCompare(b.indexName));
+}
+/** Whether `prefix` is a strict leading prefix of `columns`. */
+function isLeadingPrefix(prefix, columns) {
+    if (prefix.length === 0 || prefix.length >= columns.length)
+        return false;
+    return prefix.every((c, i) => columns[i] === c);
+}
+/**
+ * Non-unique indexes whose column list is a leading prefix of a WIDER index on
+ * the same table. A btree serves any leading-prefix lookup, so the narrow index
+ * is redundant. Pure metadata (no idx_scan needed).
+ *
+ * Uniqueness compatibility: only a NON-unique index is ever reported. A unique
+ * or primary-key prefix is load-bearing (it enforces a constraint), so it is
+ * never called redundant even when a wider index shares its leading columns.
+ */
+function findRedundantIndexes(snapshot) {
+    const byTable = new Map();
+    for (const idx of snapshot.indexes) {
+        if (!idx.isValid)
+            continue;
+        let list = byTable.get(idx.table);
+        if (!list) {
+            list = [];
+            byTable.set(idx.table, list);
+        }
+        list.push(idx);
+    }
+    const out = [];
+    for (const list of byTable.values()) {
+        for (const narrow of list) {
+            // Candidate must be a plain, non-constraint index: dropping it must not
+            // remove a uniqueness/PK/exclusion guarantee or a replica identity.
+            if (isConstraintBacking(narrow))
+                continue;
+            if (narrow.columns.length === 0)
+                continue;
+            const wider = list.find((w) => w.indexName !== narrow.indexName && isLeadingPrefix(narrow.columns, w.columns));
+            if (!wider)
+                continue;
+            out.push({
+                table: narrow.table,
+                indexName: narrow.indexName,
+                columns: narrow.columns,
+                coveredBy: wider.indexName,
+                coveredByColumns: wider.columns,
+                sizeBytes: narrow.sizeBytes ?? null,
+                dropSql: (0, index_advisor_js_1.buildDropIndexSql)(narrow.indexName, { concurrently: true }),
+            });
+        }
+    }
+    return out.sort((a, b) => a.table.localeCompare(b.table) || a.indexName.localeCompare(b.indexName));
+}
+/**
+ * The unused-index machinery scoped to doctor's OWN previously-suggested indexes:
+ * existing indexes whose name matches the `idx_<table>_<cols>` (63-byte truncated)
+ * shape doctor emits, never scanned since the stats reset. `doctorNames` maps each
+ * deterministic name to the distinct column sets that truncate to it (see
+ * `collectDoctorProbeIndexNames`); a name with more than one column set is a
+ * post-truncation collision, reported as ambiguous.
+ */
+function auditDoctorIndexes(snapshot, doctorNames, options = {}) {
+    const minScans = options.minScans ?? exports.STATS_THRESHOLDS.unusedMinScans;
+    const out = [];
+    for (const idx of snapshot.indexes) {
+        if (!idx.isValid || isConstraintBacking(idx))
+            continue;
+        const candidates = doctorNames.get(idx.indexName);
+        if (!candidates || candidates.length === 0)
+            continue;
+        if (idx.idxScan === undefined || idx.idxScan >= minScans)
+            continue;
+        out.push({
+            table: idx.table,
+            indexName: idx.indexName,
+            columns: idx.columns,
+            idxScan: idx.idxScan,
+            sizeBytes: idx.sizeBytes ?? null,
+            dropSql: (0, index_advisor_js_1.buildDropIndexSql)(idx.indexName, { concurrently: true }),
+            ambiguous: candidates.length > 1,
+        });
+    }
+    return out.sort((a, b) => a.indexName.localeCompare(b.indexName));
+}
 /**
  * Whether the snapshot is trustworthy enough to render tier verdicts. Empty,
  * unavailable, or too-young stats degrade to the topology-only report.
@@ -398,8 +541,11 @@ async function collectStatsSnapshot(options) {
         const indexRows = await run('pg_index', `SELECT c.relname AS table_name,
               ic.relname AS index_name,
               i.indisvalid, i.indisunique, i.indisprimary, i.indisreplident,
+              EXISTS (SELECT 1 FROM pg_constraint con
+                       WHERE con.conindid = i.indexrelid AND con.contype = 'x') AS is_exclusion,
               s.idx_scan::text AS idx_scan,
-              (SELECT array_agg(a.attname ORDER BY k.ord)
+              pg_relation_size(i.indexrelid)::text AS index_size,
+              (SELECT array_agg(a.attname::text ORDER BY k.ord)
                  FROM unnest(i.indkey) WITH ORDINALITY AS k(attnum, ord)
                  JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum) AS columns
          FROM pg_index i
@@ -419,6 +565,8 @@ async function collectStatsSnapshot(options) {
                     isUnique: row.indisunique,
                     isPrimary: row.indisprimary,
                     isReplicaIdent: row.indisreplident,
+                    isExclusion: row.is_exclusion,
+                    sizeBytes: row.index_size == null ? undefined : Number(row.index_size),
                 });
             }
         }
@@ -448,3 +596,71 @@ async function collectStatsSnapshot(options) {
     }
     return snapshot;
 }
+/**
+ * Read per-model workload heat from a `_turbine_metrics` table (written by
+ * `db.$observe()` with the default Postgres sink). When the table is absent, the
+ * result is `available: false` with a notice: this is the expected state when
+ * observe uses a non-Postgres sink, or when no metrics have been collected yet.
+ * Every read is best-effort; a failure degrades to unavailable, never throws.
+ */
+async function collectTableHeat(options) {
+    const windowMinutes = options.windowMinutes ?? 60;
+    const timeout = options.statementTimeoutMs ?? 5000;
+    const result = { available: false, tables: {}, notice: null };
+    if (options.models.length === 0) {
+        result.notice = 'no probed tables to correlate against workload heat.';
+        return result;
+    }
+    const { Pool } = (await Promise.resolve().then(() => __importStar(require('pg')))).default;
+    const pool = new Pool({ connectionString: options.connectionString, max: 1 });
+    try {
+        try {
+            await pool.query(`SET statement_timeout = ${Number(timeout)}`);
+        }
+        catch {
+            /* best-effort */
+        }
+        const exists = await pool
+            .query(`SELECT to_regclass('_turbine_metrics')::text AS reg`)
+            .then((r) => r.rows[0]?.reg ?? null)
+            .catch(() => null);
+        if (!exists) {
+            result.notice =
+                'the _turbine_metrics table was not found: heat boosting is unavailable (observe may be using a non-Postgres sink, or no metrics have been collected yet).';
+            return result;
+        }
+        const rows = await pool
+            .query(`SELECT model,
+                sum(count)::float8::text AS total_count,
+                max(p95_ms)::text AS p95,
+                count(*)::text AS buckets
+           FROM _turbine_metrics
+          WHERE bucket >= NOW() - (INTERVAL '1 minute' * $1) AND model = ANY($2)
+          GROUP BY model`, [windowMinutes, options.models])
+            .then((r) => r.rows)
+            .catch(() => null);
+        if (rows === null) {
+            result.notice = 'reading _turbine_metrics failed: heat boosting is unavailable.';
+            return result;
+        }
+        result.available = true;
+        for (const row of rows) {
+            const total = Number(row.total_count);
+            if (!Number.isFinite(total))
+                continue;
+            result.tables[row.model] = {
+                queriesPerMin: total / Math.max(1, windowMinutes),
+                p95Ms: row.p95 == null ? 0 : Number(row.p95),
+            };
+        }
+    }
+    finally {
+        try {
+            await pool.end();
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    return result;
+}

package/dist/cjs/index.js

@@ -34,8 +34,8 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.withDbFieldNames = exports.snakeToPascal = exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
-exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = void 0;
+exports.snakeToCamel = exports.singularize = exports.pgTypeToTs = exports.pgArrayType = exports.normalizeKeyColumns = exports.isDateType = exports.camelToSnake = exports.validateChannel = exports.QueryInterface = exports.pipelineSupported = exports.executePipeline = exports.PgMetricsSink = exports.HttpJsonSink = exports.hasRelationFields = exports.executeNestedUpdate = exports.executeNestedCreate = exports.introspect = exports.generate = exports.wrapPgError = exports.ValidationError = exports.UnsupportedFeatureError = exports.UniqueConstraintError = exports.TurbineErrorCode = exports.TurbineError = exports.TimeoutError = exports.setErrorMessageMode = exports.SerializationFailureError = exports.RelationError = exports.ReadOnlyError = exports.PipelineError = exports.OptimisticLockError = exports.NotNullViolationError = exports.NotFoundError = exports.MigrationError = exports.getErrorMessageMode = exports.ForeignKeyError = exports.ExclusionConstraintError = exports.DeadlockError = exports.ConnectionError = exports.CircularRelationError = exports.CheckConstraintError = exports.postgresDialect = exports.withRetry = exports.TurbineClient = exports.TransactionClient = exports.yugabytedb = exports.timescale = exports.postgresql = exports.cockroachdb = exports.alloydb = void 0;
+exports.TypedSqlQuery = exports.buildTypedSql = exports.turbineHttp = exports.defineSeed = exports.schemaToSQLString = exports.schemaToSQL = exports.schemaPush = exports.schemaDiff = exports.DestructivePushRefusal = exports.schemaDefToMetadata = exports.table = exports.isDocFieldIndexDef = exports.defineSchema = exports.column = exports.ColumnBuilder = exports.applyManyToManyRelations = exports.withDbFieldNames = exports.snakeToPascal = void 0;
 var index_js_1 = require("./adapters/index.js");
 Object.defineProperty(exports, "alloydb", { enumerable: true, get: function () { return index_js_1.alloydb; } });
 Object.defineProperty(exports, "cockroachdb", { enumerable: true, get: function () { return index_js_1.cockroachdb; } });
@@ -85,6 +85,10 @@ var nested_write_js_1 = require("./nested-write.js");
 Object.defineProperty(exports, "executeNestedCreate", { enumerable: true, get: function () { return nested_write_js_1.executeNestedCreate; } });
 Object.defineProperty(exports, "executeNestedUpdate", { enumerable: true, get: function () { return nested_write_js_1.executeNestedUpdate; } });
 Object.defineProperty(exports, "hasRelationFields", { enumerable: true, get: function () { return nested_write_js_1.hasRelationFields; } });
+// Observability
+var observe_js_1 = require("./observe.js");
+Object.defineProperty(exports, "HttpJsonSink", { enumerable: true, get: function () { return observe_js_1.HttpJsonSink; } });
+Object.defineProperty(exports, "PgMetricsSink", { enumerable: true, get: function () { return observe_js_1.PgMetricsSink; } });
 // Pipeline
 var pipeline_js_1 = require("./pipeline.js");
 Object.defineProperty(exports, "executePipeline", { enumerable: true, get: function () { return pipeline_js_1.executePipeline; } });