turbine-orm 0.46.0 → 0.47.0

package/dist/index-stats.d.ts

@@ -68,6 +68,18 @@ export declare const STATS_THRESHOLDS: {
     readonly appendHeavyInsertRatio: 0.95;
     /** ... and seq_scan at or below this ("near-zero probe reads") → scrutinize. */
     readonly 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".
+     */
+    readonly 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).
+     */
+    readonly heatMinQueriesPerMin: 1;
 };
 /** Per-table live statistics. Any field may be absent when its catalog read degraded. */
 export interface TableStats {
@@ -99,6 +111,10 @@ export interface IndexStat {
     isUnique: boolean;
     isPrimary: boolean;
     isReplicaIdent: boolean;
+    /** Backs an exclusion constraint (pg_constraint.contype = 'x'). */
+    isExclusion?: boolean;
+    /** pg_relation_size of the index heap, bytes. Size reclaimed by a drop. */
+    sizeBytes?: number;
 }
 /**
  * A point-in-time read of the statistics the triage needs. Every part is
@@ -150,9 +166,18 @@ export interface ScoredMissingIndex {
     hotWarning: string | null;
     /** When true, the emitted index should be a partial `WHERE col IS NOT NULL`. */
     partialNotNull: boolean;
-    /** Sort key within a tier: bigger, more-probed tables first. */
+    /** True when workload heat lifted this finding's priority (see {@link TableHeatEntry}). */
+    heatBoosted: boolean;
+    /** Sort key within a tier: bigger, more-probed tables first; hot tables first of all. */
     benefitScore: number;
 }
+/** Per-table workload heat, derived from the _turbine_metrics per-minute aggregates. */
+export interface TableHeatEntry {
+    /** Average queries per minute across the observed window. */
+    queriesPerMin: number;
+    /** Worst observed p95 latency (ms) across the window. */
+    p95Ms: number;
+}
 /** The subset of a topology finding the scorer needs. */
 export interface ScorableMissingIndex {
     table: string;
@@ -165,7 +190,7 @@ export declare function formatBytes(bytes: number | null | undefined): string;
  * Score a single missing-index finding against a snapshot. Pure and total:
  * every unknown degrades to a caveat rather than a fabricated number.
  */
-export declare function scoreMissingIndex(missing: ScorableMissingIndex, snapshot: StatsSnapshot): ScoredMissingIndex;
+export declare function scoreMissingIndex(missing: ScorableMissingIndex, snapshot: StatsSnapshot, heat?: TableHeatEntry): ScoredMissingIndex;
 export interface InvalidIndex {
     table: string;
     indexName: string;
@@ -179,6 +204,81 @@ export interface InvalidIndex {
  * skips the corpse, so the fix is DROP INDEX CONCURRENTLY then rerun.
  */
 export declare function findInvalidIndexes(snapshot: StatsSnapshot): InvalidIndex[];
+/** A never-scanned index and the DROP statement that would reclaim it. */
+export interface UnusedIndex {
+    table: string;
+    indexName: string;
+    columns: string[];
+    /** idx_scan since the last stats reset (0 or below --min-scans). */
+    idxScan: number;
+    /** Size reclaimed by the drop, bytes (null when the size read degraded). */
+    sizeBytes: number | null;
+    /** `DROP INDEX CONCURRENTLY IF EXISTS`: printed only, never written to a migration. */
+    dropSql: string;
+}
+/**
+ * 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.
+ */
+export declare function findUnusedIndexes(snapshot: StatsSnapshot, options?: {
+    minScans?: number;
+}): UnusedIndex[];
+/** A redundant index whose columns are a leading prefix of a wider index. */
+export interface RedundantIndex {
+    table: string;
+    indexName: string;
+    columns: string[];
+    /** The wider index that already covers this one's leading-prefix lookups. */
+    coveredBy: string;
+    coveredByColumns: string[];
+    sizeBytes: number | null;
+    dropSql: string;
+}
+/**
+ * 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.
+ */
+export declare function findRedundantIndexes(snapshot: StatsSnapshot): RedundantIndex[];
+/**
+ * A `doctor --audit` finding: an existing index that matches doctor's own
+ * deterministic naming AND has not been scanned since the stats reset.
+ */
+export interface DoctorIndexAudit {
+    table: string;
+    indexName: string;
+    columns: string[];
+    idxScan: number;
+    sizeBytes: number | null;
+    dropSql: string;
+    /**
+     * True when the truncated (63-byte) name collides across DIFFERENT column sets
+     * in the schema's probes, so which suggestion this index realizes is
+     * ambiguous. Reported as ambiguous instead of a confident drop verdict.
+     */
+    ambiguous: boolean;
+}
+/**
+ * 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.
+ */
+export declare function auditDoctorIndexes(snapshot: StatsSnapshot, doctorNames: Map<string, Array<{
+    table: string;
+    columns: string[];
+}>>, options?: {
+    minScans?: number;
+}): DoctorIndexAudit[];
 /**
  * Whether the snapshot is trustworthy enough to render tier verdicts. Empty,
  * unavailable, or too-young stats degrade to the topology-only report.
@@ -206,3 +306,28 @@ export interface CollectSnapshotOptions {
  * signal rather than the whole snapshot.
  */
 export declare function collectStatsSnapshot(options: CollectSnapshotOptions): Promise<StatsSnapshot>;
+export interface CollectTableHeatOptions {
+    /** Where _turbine_metrics lives (the app DB, or a separate --metrics-url DB). */
+    connectionString: string;
+    /** Model names to read heat for (the probed table names). */
+    models: string[];
+    /** Trailing window of per-minute buckets to average, minutes. Default 60. */
+    windowMinutes?: number;
+    statementTimeoutMs?: number;
+}
+export interface TableHeatResult {
+    /** True when _turbine_metrics existed and was read. False = heat boosting off. */
+    available: boolean;
+    /** Per-model heat, keyed by model (= table) name. */
+    tables: Record<string, TableHeatEntry>;
+    /** One honesty line when heat could not be sourced (absent table / non-pg sink). */
+    notice: string | null;
+}
+/**
+ * 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.
+ */
+export declare function collectTableHeat(options: CollectTableHeatOptions): Promise<TableHeatResult>;

package/dist/index-stats.js

@@ -72,6 +72,18 @@ export const 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. */
 export function emptyStatsSnapshot(notices = []) {
@@ -107,7 +119,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.
  */
-export function scoreMissingIndex(missing, snapshot) {
+export function scoreMissingIndex(missing, snapshot, heat) {
     const t = STATS_THRESHOLDS;
     const stats = snapshot.tables[missing.table];
     const probingRelations = missing.probes.length;
@@ -219,8 +231,17 @@ export 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,
@@ -229,6 +250,7 @@ export function scoreMissingIndex(missing, snapshot) {
         metrics,
         hotWarning,
         partialNotNull,
+        heatBoosted,
         benefitScore,
     };
 }
@@ -255,6 +277,123 @@ export 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.
+ */
+export function findUnusedIndexes(snapshot, options = {}) {
+    const minScans = options.minScans ?? 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: 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.
+ */
+export 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: 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.
+ */
+export function auditDoctorIndexes(snapshot, doctorNames, options = {}) {
+    const minScans = options.minScans ?? 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: 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.
@@ -356,8 +495,11 @@ export 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
@@ -377,6 +519,8 @@ export 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),
                 });
             }
         }
@@ -406,3 +550,71 @@ export 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.
+ */
+export 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 import('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/index.d.ts

@@ -41,7 +41,7 @@ export { CheckConstraintError, CircularRelationError, ConnectionError, DeadlockE
 export { type GenerateOptions, generate } from './generate.js';
 export { type IntrospectOptions, introspect } from './introspect.js';
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, type NestedWriteContext, } from './nested-write.js';
-export type { ObserveConfig, ObserveHandle } from './observe.js';
+export { HttpJsonSink, type HttpJsonSinkOptions, type MetricsFlushBatch, type MetricsFlushRow, type ObserveConfig, type ObserveHandle, type ObserveSink, PgMetricsSink, type PgMetricsSinkOptions, } from './observe.js';
 export { executePipeline, type PipelineOptions, type PipelineResults, pipelineSupported } from './pipeline.js';
 export { type AggregateArgs, type AggregateResult, type ArrayFilter, type ColumnRef, type ConnectOrCreateOp, type CountArgs, type CreateArgs, type CreateDataInput, type CreateManyArgs, type DeferredQuery, type DeleteArgs, type DeleteManyArgs, type FieldResult, type FindManyArgs, type FindManyStreamArgs, type FindUniqueArgs, type GlobalFilters, type GroupByAggregateSpec, type GroupByArgs, type GroupByDistinctOn, type GroupByResult, type HavingClause, type JsonFilter, type JsonPathAggregateTarget, type JsonPathGroupKey, type JsonPathOrderBy, type MiddlewareFn, type NestedCreateOp, type NestedUpdateOp, type NestedUpdateOpItem, type NestedUpsertOpItem, type OmitResult, type OrderByClause, type OrderByObject, type OrderDirection, type QueryEvent, type QueryEventListener, QueryInterface, type QueryResult, type RelationDescriptor, type RelationFilter, type RelationLoadStrategy, type RelationPickBy, type RelationPickOrderBy, type SelectResult, type SkipGlobalFilters, type TextSearchFilter, type TypedWithClause, type UpdateArgs, type UpdateDataInput, type UpdateInput, type UpdateManyArgs, type UpdateOperatorInput, type UpsertArgs, type VectorDistanceFilter, type VectorFilter, type VectorMetric, type VectorOrderBy, type VectorOrderByDistance, type WhereClause, type WhereOperator, type WhereValue, type WithClause, type WithOptions, type WithOrderByObject, type WithResult, } from './query/index.js';
 export { type ActiveSubscription, type NotificationHandler, type Subscription, validateChannel } from './realtime.js';

package/dist/index.js

@@ -44,6 +44,8 @@ export { generate } from './generate.js';
 export { introspect } from './introspect.js';
 // Nested writes
 export { executeNestedCreate, executeNestedUpdate, hasRelationFields, } from './nested-write.js';
+// Observability
+export { HttpJsonSink, PgMetricsSink, } from './observe.js';
 // Pipeline
 export { executePipeline, pipelineSupported } from './pipeline.js';
 // Query builder

package/dist/observe.d.ts

@@ -1,28 +1,109 @@
 /**
- * turbine-orm — Observability module
+ * turbine-orm: Observability module
  *
  * Buffers query metrics in memory (keyed by model:action per minute bucket),
- * then periodically flushes aggregates (count, avg, p50, p95, p99, errors)
- * to a dedicated _turbine_metrics table. Uses a separate 1-connection pool
- * so metrics writes never contend with the application pool.
+ * then periodically flushes aggregates (count, avg, p50, p95, p99, errors) to a
+ * pluggable {@link ObserveSink}. The default sink writes to a dedicated
+ * `_turbine_metrics` Postgres table over its own 1-connection pool, so metrics
+ * writes never contend with the application pool; alternative sinks (for example
+ * {@link HttpJsonSink}) can forward the same aggregates elsewhere.
+ *
+ * The aggregation privacy posture is deliberate: a batch carries only the
+ * model/action identity, the counts, and the latency percentiles. It never
+ * carries SQL text or bound parameter values.
  */
 import type { QueryEventListener } from './query/index.js';
 export interface ObserveConfig {
-    connectionString: string;
+    /**
+     * Metrics database connection string for the default Postgres sink. Optional
+     * when a {@link ObserveConfig.sink} is supplied; at least one of the two must
+     * be present.
+     */
+    connectionString?: string;
     flushIntervalMs?: number;
     retentionDays?: number;
+    /**
+     * A custom flush target. When omitted, the engine writes to `_turbine_metrics`
+     * via the default Postgres sink (byte-identical to the pre-sink writer).
+     */
+    sink?: ObserveSink;
 }
 export interface ObserveHandle {
     stop(): Promise<void>;
 }
+/** One per-bucket aggregate row. Identity + numbers only: no SQL, no params. */
+export interface MetricsFlushRow {
+    /** Minute bucket the aggregate belongs to. */
+    bucket: Date;
+    model: string;
+    action: string;
+    count: number;
+    avg: number;
+    p50: number;
+    p95: number;
+    p99: number;
+    errors: number;
+}
+/** A batch of aggregate rows handed to a sink on each flush. */
+export interface MetricsFlushBatch {
+    rows: MetricsFlushRow[];
+}
+/**
+ * A pluggable flush target for the observe engine. `init` runs once at startup
+ * (create tables, open connections); `flush` receives each aggregate batch;
+ * `stop` tears down on shutdown. A sink must never let a flush error escape into
+ * the application: metrics are best-effort by contract.
+ */
+export interface ObserveSink {
+    init?(): Promise<void>;
+    flush(batch: MetricsFlushBatch): Promise<void>;
+    stop?(): Promise<void>;
+}
 declare function floorToMinute(date: Date): Date;
 declare function percentile(sorted: number[], p: number): number;
-export declare class ObserveEngine {
+export interface PgMetricsSinkOptions {
+    connectionString: string;
+    retentionDays?: number;
+}
+/**
+ * The default flush target: upserts each aggregate row into `_turbine_metrics`
+ * and prunes rows older than `retentionDays`. The SQL and per-row/retention
+ * ordering are byte-identical to the pre-sink `ObserveEngine.flush` writer.
+ */
+export declare class PgMetricsSink implements ObserveSink {
     private readonly pool;
+    private readonly retentionDays;
+    constructor(options: PgMetricsSinkOptions);
+    init(): Promise<void>;
+    flush(batch: MetricsFlushBatch): Promise<void>;
+    stop(): Promise<void>;
+}
+export interface HttpJsonSinkOptions {
+    /** Endpoint that receives POSTed JSON batches. */
+    url: string;
+    /** Extra request headers (for example an auth token). */
+    headers?: Record<string, string>;
+    /** Override the fetch implementation (defaults to the global `fetch`). */
+    fetchFunction?: typeof fetch;
+}
+/**
+ * Forwards each aggregate batch to an HTTP endpoint as a JSON POST. Fire-and-
+ * forget: a failed request is swallowed and never throws, and there are no
+ * retries beyond the engine's next scheduled flush. Aggregates only: the body
+ * carries no SQL text and no parameter values.
+ */
+export declare class HttpJsonSink implements ObserveSink {
+    private readonly url;
+    private readonly headers;
+    private readonly fetchFn;
+    constructor(options: HttpJsonSinkOptions);
+    flush(batch: MetricsFlushBatch): Promise<void>;
+}
+export declare class ObserveEngine {
+    private readonly sink;
     private readonly buffer;
     private currentBucket;
     private readonly flushIntervalMs;
-    private readonly retentionDays;
     private timer;
     private readonly listener;
     private stopped;