@noego/telemetry 0.0.5 → 0.1.0

package/dist/cli/telemetry_cli.cjs

@@ -35,7 +35,7 @@ __export(telemetry_cli_exports, {
   runTelemetryCli: () => runTelemetryCli
 });
 module.exports = __toCommonJS(telemetry_cli_exports);
-var import_node_fs3 = require("fs");
+var import_node_fs5 = require("fs");
 
 // src/platform/node/telemetry_configuration_parser.ts
 var import_node_path = require("path");
@@ -100,11 +100,15 @@ var MetricDefinitionContract = class {
     if (!eventSelector || !bracket) {
       return { ok: false, error: `Invalid metric selector ${selector}` };
     }
+    const groupBy = bracket === "*" ? [] : bracket.split(",").map((field) => field.trim());
+    if (groupBy.some((field) => field.length === 0)) {
+      return { ok: false, error: `Invalid metric selector ${selector}` };
+    }
     return {
       ok: true,
       value: {
         selector: eventSelector,
-        groupBy: bracket === "*" ? [] : [bracket],
+        groupBy,
         wildcardUngrouped: bracket === "*"
       }
     };
@@ -1820,24 +1824,200 @@ var MetricGraphRenderer = class {
   }
 };
 
+// src/cli/history_metric_reader.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = require("path");
+var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var HISTORY_DATABASE_NAME = "history.db";
+var AGGREGATES = /* @__PURE__ */ new Set(["count", "sum", "min", "max", "last", "avg"]);
+function historyDatabasePath(target) {
+  return (0, import_node_path2.join)((0, import_node_path2.dirname)(target.path), HISTORY_DATABASE_NAME);
+}
+var HistoryMetricReader = class _HistoryMetricReader {
+  constructor(db, definitions) {
+    this.db = db;
+    this.definitions = definitions;
+  }
+  db;
+  definitions;
+  static open(databasePath, definitions) {
+    const db = new import_better_sqlite3.default(databasePath, { readonly: true, fileMustExist: true });
+    db.pragma("busy_timeout = 1000");
+    db.pragma("query_only = ON");
+    return new _HistoryMetricReader(db, definitions);
+  }
+  static exists(databasePath) {
+    return (0, import_node_fs2.existsSync)(databasePath);
+  }
+  metrics(query, targetId) {
+    if (query.toMs <= query.fromMs) {
+      return { ok: false, error: { kind: "invalid-query", message: "--to must be after --from" } };
+    }
+    const invalidMeasurement = query.measurements.find((measurement) => !isMeasurement(measurement));
+    if (invalidMeasurement !== void 0) {
+      return {
+        ok: false,
+        error: {
+          kind: "invalid-query",
+          message: `Unknown measurement ${invalidMeasurement}; use count or <field>.<sum|min|max|last|count|avg>`
+        }
+      };
+    }
+    const versions = this.registeredVersions(query.metric);
+    if (versions.length === 0) {
+      return {
+        ok: false,
+        error: { kind: "invalid-query", message: `Metric ${query.metric} has no projection in history.db` }
+      };
+    }
+    const resolutionMs = this.resolveResolution(query, versions);
+    if (resolutionMs === null) {
+      return {
+        ok: false,
+        error: { kind: "invalid-query", message: `Metric ${query.metric} is not projected at the requested resolution` }
+      };
+    }
+    for (let index = versions.length - 1; index >= 0; index -= 1) {
+      const version = versions[index];
+      const buckets = this.readBuckets(query, version, resolutionMs);
+      if (buckets.length === 0) continue;
+      const olderVersions = versions.slice(0, index);
+      return {
+        ok: true,
+        value: Object.freeze({
+          targetId,
+          metric: query.metric,
+          segments: [Object.freeze({
+            fromMs: query.fromMs,
+            toMs: query.toMs,
+            resolutionMs,
+            isAggregated: true,
+            definitionVersion: version,
+            buckets
+          })],
+          gaps: [],
+          nextCursor: null,
+          partialFailures: olderVersions.map((older) => Object.freeze({
+            targetId,
+            reason: `version ${older} buckets omitted; only version ${version} returned`
+          }))
+        })
+      };
+    }
+    return {
+      ok: true,
+      value: Object.freeze({
+        targetId,
+        metric: query.metric,
+        segments: [],
+        gaps: [Object.freeze({ fromMs: query.fromMs, toMs: query.toMs, reason: "not-materialized" })],
+        nextCursor: null,
+        partialFailures: []
+      })
+    };
+  }
+  close() {
+    if (this.db.open) this.db.close();
+  }
+  registeredVersions(metric) {
+    const rows = this.db.prepare(
+      "SELECT projection_version FROM trace_projection_definitions WHERE projection_name = ? ORDER BY projection_version"
+    ).all(metric);
+    return rows.map((row) => row.projection_version);
+  }
+  resolveResolution(query, versions) {
+    const available = this.definitions.filter((definition) => definition.name === query.metric && versions.includes(definition.version)).flatMap((definition) => [...definition.resolutionsMs]);
+    const resolutions = [...new Set(available.length > 0 ? available : this.storedResolutions(query.metric))].sort((a, b) => a - b);
+    if (resolutions.length === 0) return null;
+    if (query.resolution !== "auto") {
+      return resolutions.includes(query.resolution) ? query.resolution : null;
+    }
+    const span = query.toMs - query.fromMs;
+    return resolutions.find((resolution) => Math.ceil(span / resolution) <= query.limit) ?? resolutions[resolutions.length - 1];
+  }
+  storedResolutions(metric) {
+    const rows = this.db.prepare(
+      "SELECT DISTINCT resolution_ms FROM trace_metric_buckets WHERE projection_name = ?"
+    ).all(metric);
+    return rows.map((row) => row.resolution_ms);
+  }
+  readBuckets(query, version, resolutionMs) {
+    const rows = this.db.prepare(`
+      SELECT projection_version, bucket_start_ms, dimensions_json, count, values_json
+      FROM trace_metric_buckets
+      WHERE projection_name = ? AND projection_version = ? AND resolution_ms = ?
+        AND bucket_start_ms >= ? AND bucket_start_ms < ?
+      ORDER BY bucket_start_ms ${query.order === "desc" ? "DESC" : "ASC"}, dimension_key
+    `).all(query.metric, version, resolutionMs, query.fromMs, query.toMs);
+    const buckets = [];
+    for (const row of rows) {
+      const dimensions = JSON.parse(row.dimensions_json);
+      if (!matchesWhere(dimensions, query.where)) continue;
+      const values = JSON.parse(row.values_json);
+      buckets.push(Object.freeze({
+        startMs: row.bucket_start_ms,
+        endMs: row.bucket_start_ms + resolutionMs,
+        dimensions,
+        values: selectMeasurements(query.measurements, row.count, values)
+      }));
+      if (buckets.length >= query.limit) break;
+    }
+    return buckets;
+  }
+};
+function isMeasurement(measurement) {
+  if (measurement === "count") return true;
+  const dot = measurement.lastIndexOf(".");
+  return dot > 0 && AGGREGATES.has(measurement.slice(dot + 1));
+}
+function selectMeasurements(measurements, bucketCount, values) {
+  const selected = {};
+  for (const measurement of measurements) {
+    if (measurement === "count") {
+      selected.count = bucketCount;
+      continue;
+    }
+    const dot = measurement.lastIndexOf(".");
+    const field = measurement.slice(0, dot);
+    const aggregate = measurement.slice(dot + 1);
+    const state = values[field];
+    if (state === void 0) continue;
+    const value = aggregate === "avg" ? state.count > 0 ? state.sum / state.count : 0 : state[aggregate];
+    if (!Number.isFinite(value)) continue;
+    const existing = selected[field];
+    selected[field] = { ...typeof existing === "object" ? existing : {}, [aggregate]: value };
+  }
+  return Object.freeze(selected);
+}
+function matchesWhere(dimensions, where) {
+  for (const [key, filter] of Object.entries(where)) {
+    const actual = dimensions[key];
+    if (actual === void 0) return false;
+    const accepted = Array.isArray(filter) ? filter : [filter];
+    if (!accepted.some((candidate) => String(candidate) === actual)) return false;
+  }
+  return true;
+}
+
 // src/cli/offline_sqlite_session.ts
 var import_node_crypto2 = require("crypto");
-var import_node_path3 = require("path");
+var import_node_fs4 = require("fs");
+var import_node_path4 = require("path");
 var import_node_url = require("url");
 var import_proper = require("@noego/proper");
-var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var import_better_sqlite32 = __toESM(require("better-sqlite3"), 1);
 var import_adapters = require("sqlstack/adapters");
 
 // src/storage/sqlite_ownership_lease.ts
-var import_node_fs2 = require("fs");
-var import_node_path2 = require("path");
+var import_node_fs3 = require("fs");
+var import_node_path3 = require("path");
 var SqliteOwnershipLease = class {
   constructor(options) {
     this.options = options;
-    (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(options.databasePath), { recursive: true });
-    const canonicalDirectory = (0, import_node_fs2.realpathSync)((0, import_node_path2.dirname)((0, import_node_path2.resolve)(options.databasePath)));
-    const databaseName = (0, import_node_path2.resolve)(options.databasePath).slice((0, import_node_path2.dirname)((0, import_node_path2.resolve)(options.databasePath)).length + 1);
-    this.canonicalDatabasePath = (0, import_node_path2.resolve)(canonicalDirectory, databaseName);
+    (0, import_node_fs3.mkdirSync)((0, import_node_path3.dirname)(options.databasePath), { recursive: true });
+    const canonicalDirectory = (0, import_node_fs3.realpathSync)((0, import_node_path3.dirname)((0, import_node_path3.resolve)(options.databasePath)));
+    const databaseName = (0, import_node_path3.resolve)(options.databasePath).slice((0, import_node_path3.dirname)((0, import_node_path3.resolve)(options.databasePath)).length + 1);
+    this.canonicalDatabasePath = (0, import_node_path3.resolve)(canonicalDirectory, databaseName);
     this.leasePath = `${this.canonicalDatabasePath}.telemetry-owner.json`;
   }
   options;
@@ -1880,14 +2060,14 @@ var SqliteOwnershipLease = class {
     });
   }
   release() {
-    if (!this.held || !(0, import_node_fs2.existsSync)(this.leasePath)) {
+    if (!this.held || !(0, import_node_fs3.existsSync)(this.leasePath)) {
       this.held = false;
       return;
     }
     const current = this.readRecord();
     if (current.ok && current.value.processToken === this.options.processToken) {
       try {
-        (0, import_node_fs2.rmSync)(this.leasePath, { force: true });
+        (0, import_node_fs3.rmSync)(this.leasePath, { force: true });
       } catch {
       }
     }
@@ -1916,14 +2096,14 @@ var SqliteOwnershipLease = class {
   writeExclusive(record) {
     let descriptor = null;
     try {
-      descriptor = (0, import_node_fs2.openSync)(this.leasePath, "wx", 384);
-      (0, import_node_fs2.writeFileSync)(descriptor, JSON.stringify(record), { encoding: "utf8" });
-      (0, import_node_fs2.closeSync)(descriptor);
+      descriptor = (0, import_node_fs3.openSync)(this.leasePath, "wx", 384);
+      (0, import_node_fs3.writeFileSync)(descriptor, JSON.stringify(record), { encoding: "utf8" });
+      (0, import_node_fs3.closeSync)(descriptor);
       return { ok: true, value: void 0 };
     } catch (cause) {
       if (descriptor !== null) {
         try {
-          (0, import_node_fs2.closeSync)(descriptor);
+          (0, import_node_fs3.closeSync)(descriptor);
         } catch {
         }
       }
@@ -1933,12 +2113,12 @@ var SqliteOwnershipLease = class {
   writeReplace(record) {
     const temporaryPath = `${this.leasePath}.${this.options.processToken}.tmp`;
     try {
-      (0, import_node_fs2.writeFileSync)(temporaryPath, JSON.stringify(record), { encoding: "utf8", mode: 384 });
-      (0, import_node_fs2.renameSync)(temporaryPath, this.leasePath);
+      (0, import_node_fs3.writeFileSync)(temporaryPath, JSON.stringify(record), { encoding: "utf8", mode: 384 });
+      (0, import_node_fs3.renameSync)(temporaryPath, this.leasePath);
       return { ok: true, value: void 0 };
     } catch (cause) {
       try {
-        (0, import_node_fs2.rmSync)(temporaryPath, { force: true });
+        (0, import_node_fs3.rmSync)(temporaryPath, { force: true });
       } catch {
       }
       return { ok: false, error: this.errorMessage(cause) };
@@ -1946,7 +2126,7 @@ var SqliteOwnershipLease = class {
   }
   readRecord() {
     try {
-      const parsed = JSON.parse((0, import_node_fs2.readFileSync)(this.leasePath, "utf8"));
+      const parsed = JSON.parse((0, import_node_fs3.readFileSync)(this.leasePath, "utf8"));
       if (!this.isLeaseRecord(parsed)) {
         return { ok: false, error: `Invalid telemetry ownership lease at ${this.leasePath}` };
       }
@@ -1970,8 +2150,8 @@ var SqliteOwnershipLease = class {
     }
     try {
       const stalePath = `${this.leasePath}.stale.${current.value.processToken}`;
-      (0, import_node_fs2.renameSync)(this.leasePath, stalePath);
-      (0, import_node_fs2.rmSync)(stalePath, { force: true });
+      (0, import_node_fs3.renameSync)(this.leasePath, stalePath);
+      (0, import_node_fs3.rmSync)(stalePath, { force: true });
       return { ok: true, value: void 0 };
     } catch (cause) {
       return { ok: false, error: this.errorMessage(cause) };
@@ -4366,7 +4546,7 @@ var ReadOnlySqlGuard = class {
 
 // src/cli/offline_sqlite_session.ts
 var import_meta = {};
-var MIGRATIONS_DIRECTORY = typeof __dirname === "string" ? (0, import_node_path3.resolve)(__dirname, "../../migrations") : (0, import_node_url.fileURLToPath)(new URL("../../migrations/", import_meta.url));
+var MIGRATIONS_DIRECTORY = typeof __dirname === "string" ? (0, import_node_path4.resolve)(__dirname, "../../migrations") : (0, import_node_url.fileURLToPath)(new URL("../../migrations/", import_meta.url));
 var OfflineSqliteTelemetrySession = class _OfflineSqliteTelemetrySession {
   constructor(target, mode, definitions, now, sqlGuard) {
     this.target = target;
@@ -4508,6 +4688,87 @@ var OfflineSqliteTelemetrySession = class _OfflineSqliteTelemetrySession {
     this.verifySchema();
     return this.migrationStatus();
   }
+  async compact() {
+    this.requireMaintenanceMode();
+    const connection = this.requireConnection();
+    const maintenanceTable = this.requireTableMap().physical("maintenanceRuns");
+    const runId = (0, import_node_crypto2.randomUUID)();
+    const startedAtMs = this.now();
+    connection.prepare(
+      `INSERT INTO "${maintenanceTable}" (
+         target_id, run_id, state, stage, started_at_ms,
+         completed_at_ms, affected_rows, affected_pages, detail
+       ) VALUES (?, ?, 'started', 'compaction', ?, NULL, 0, 0, ?)`
+    ).run(this.target.targetId, runId, startedAtMs, "offline-cli; outcome=started");
+    try {
+      const before = this.compactionSnapshot();
+      connection.pragma("wal_checkpoint(TRUNCATE)");
+      const checkpointed = this.compactionSnapshot();
+      this.assertCompactionSpace(checkpointed);
+      connection.pragma("auto_vacuum = INCREMENTAL");
+      connection.exec("VACUUM");
+      connection.pragma("wal_checkpoint(TRUNCATE)");
+      const after = this.compactionSnapshot();
+      if (after.autoVacuum !== 2) {
+        throw new Error("Telemetry compaction did not enable auto_vacuum=INCREMENTAL");
+      }
+      const completedAtMs = this.now();
+      const result = Object.freeze({
+        targetId: this.target.targetId,
+        autoVacuum: "incremental",
+        pageSize: checkpointed.pageSize,
+        pagesBefore: checkpointed.pageCount,
+        pagesAfter: after.pageCount,
+        freePagesBefore: checkpointed.freePages,
+        freePagesAfter: after.freePages,
+        reclaimedPages: Math.max(0, checkpointed.pageCount - after.pageCount),
+        databaseBytesBefore: before.databaseBytes,
+        databaseBytesAfter: after.databaseBytes,
+        walBytesBefore: before.walBytes,
+        walBytesAfter: after.walBytes,
+        reclaimedBytes: Math.max(
+          0,
+          before.databaseBytes + before.walBytes - after.databaseBytes - after.walBytes
+        ),
+        elapsedMs: completedAtMs - startedAtMs
+      });
+      connection.prepare(
+        `UPDATE "${maintenanceTable}"
+         SET state = 'completed', completed_at_ms = ?, affected_pages = ?, detail = ?
+         WHERE target_id = ? AND run_id = ? AND stage = 'compaction'`
+      ).run(
+        completedAtMs,
+        result.reclaimedPages,
+        JSON.stringify({
+          mode: "offline-cli",
+          outcome: "completed",
+          reclaimedBytes: result.reclaimedBytes,
+          walBytesBefore: result.walBytesBefore,
+          walBytesAfter: result.walBytesAfter,
+          autoVacuum: result.autoVacuum
+        }),
+        this.target.targetId,
+        runId
+      );
+      return result;
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      try {
+        connection.prepare(
+          `UPDATE "${maintenanceTable}"
+           SET state = 'failed', completed_at_ms = ?, detail = ?
+           WHERE target_id = ? AND run_id = ? AND stage = 'compaction'`
+        ).run(
+          this.now(),
+          JSON.stringify({ mode: "offline-cli", outcome: "failed", error: message }),
+          this.target.targetId,
+          runId
+        );
+      } catch {
+      }
+      throw cause;
+    }
+  }
   async close() {
     try {
       if (this.connection?.open) {
@@ -4541,7 +4802,7 @@ var OfflineSqliteTelemetrySession = class _OfflineSqliteTelemetrySession {
         throw new Error(acquired.error);
       }
     }
-    const connection = new import_better_sqlite3.default(this.target.path, {
+    const connection = new import_better_sqlite32.default(this.target.path, {
       readonly: this.mode === "query",
       fileMustExist: true
     });
@@ -4568,6 +4829,32 @@ var OfflineSqliteTelemetrySession = class _OfflineSqliteTelemetrySession {
       }
     }
   }
+  compactionSnapshot() {
+    const connection = this.requireConnection();
+    return Object.freeze({
+      pageSize: Number(connection.pragma("page_size", { simple: true })),
+      pageCount: Number(connection.pragma("page_count", { simple: true })),
+      freePages: Number(connection.pragma("freelist_count", { simple: true })),
+      autoVacuum: Number(connection.pragma("auto_vacuum", { simple: true })),
+      databaseBytes: this.fileBytes(this.target.path),
+      walBytes: this.fileBytes(`${this.target.path}-wal`)
+    });
+  }
+  assertCompactionSpace(snapshot) {
+    const liveBytes = Math.max(0, snapshot.pageCount - snapshot.freePages) * snapshot.pageSize;
+    const reserveBytes = Math.max(64 * 1024 * 1024, Math.ceil(liveBytes * 0.05));
+    const filesystem = (0, import_node_fs4.statfsSync)((0, import_node_path4.dirname)(this.target.path));
+    const availableBytes = Number(filesystem.bavail) * Number(filesystem.bsize);
+    const requiredBytes = liveBytes + reserveBytes;
+    if (availableBytes < requiredBytes) {
+      throw new Error(
+        `Telemetry compaction requires at least ${requiredBytes} free bytes; only ${availableBytes} are available`
+      );
+    }
+  }
+  fileBytes(path) {
+    return (0, import_node_fs4.existsSync)(path) ? (0, import_node_fs4.statSync)(path).size : 0;
+  }
   verifyManifest() {
     const rows = this.requireConnection().prepare(
       `SELECT target_id, format_version, mapping_json, mapping_checksum,
@@ -4752,7 +5039,8 @@ var ALLOWED_OPTIONS = Object.freeze({
     "metric",
     "where",
     "measurement",
-    "resolution"
+    "resolution",
+    "source"
   ]),
   "metrics-graph": /* @__PURE__ */ new Set([
     ...COMMON_QUERY_OPTIONS,
@@ -4760,6 +5048,7 @@ var ALLOWED_OPTIONS = Object.freeze({
     "where",
     "measurement",
     "resolution",
+    "source",
     "type",
     "output",
     "width",
@@ -4777,6 +5066,7 @@ var ALLOWED_OPTIONS = Object.freeze({
     "limit",
     "max-duration"
   ]),
+  "sqlite-compact": /* @__PURE__ */ new Set(["config", "target", "storage-base", "format"]),
   "sqlite-migration-status": /* @__PURE__ */ new Set(["config", "target", "storage-base", "format"]),
   "sqlite-migration-up": /* @__PURE__ */ new Set(["config", "target", "storage-base", "format"])
 });
@@ -4786,6 +5076,7 @@ var COMMANDS = Object.freeze([
   { tokens: ["metrics", "query"], kind: "metrics-query" },
   { tokens: ["metrics", "graph"], kind: "metrics-graph" },
   { tokens: ["sqlite", "query"], kind: "sqlite-query" },
+  { tokens: ["sqlite", "compact"], kind: "sqlite-compact" },
   { tokens: ["sqlite", "migration", "status"], kind: "sqlite-migration-status" },
   { tokens: ["sqlite", "migration", "up"], kind: "sqlite-migration-up" }
 ]);
@@ -5064,6 +5355,22 @@ var TelemetryCliFormatter = class {
     return `${lines.join("\n")}
 `;
   }
+  compaction(result, format) {
+    if (format === "json") {
+      return this.json(result);
+    }
+    return [
+      `Target: ${result.targetId}`,
+      `Auto-vacuum: ${result.autoVacuum}`,
+      `Pages: ${result.pagesBefore} -> ${result.pagesAfter} (${result.reclaimedPages} reclaimed)`,
+      `Freelist: ${result.freePagesBefore} -> ${result.freePagesAfter}`,
+      `Database bytes: ${result.databaseBytesBefore} -> ${result.databaseBytesAfter}`,
+      `WAL bytes: ${result.walBytesBefore} -> ${result.walBytesAfter}`,
+      `Filesystem bytes reclaimed: ${result.reclaimedBytes}`,
+      `Elapsed ms: ${result.elapsedMs}`,
+      ""
+    ].join("\n");
+  }
   migrations(result, format) {
     if (format === "json") {
       return this.json(result);
@@ -5140,7 +5447,7 @@ var TelemetryCli = class {
     this.configurationParser = options.configurationParser ?? new NodeTelemetryConfigurationParser();
     this.stdout = options.stdout ?? ((text) => process.stdout.write(text));
     this.stderr = options.stderr ?? ((text) => process.stderr.write(text));
-    this.writeOutputFile = options.writeOutputFile ?? ((path, content) => (0, import_node_fs3.writeFileSync)(path, content, "utf8"));
+    this.writeOutputFile = options.writeOutputFile ?? ((path, content) => (0, import_node_fs5.writeFileSync)(path, content, "utf8"));
     this.now = options.now ?? (() => Date.now());
     this.createSession = options.createSession ?? ((configuration, target, mode) => OfflineSqliteTelemetrySession.create(target, mode, configuration.metrics, this.now));
   }
@@ -5171,6 +5478,10 @@ var TelemetryCli = class {
       storageBaseDirectory === null ? {} : { storageBaseDirectory }
     );
     const target = this.resolveTarget(configuration, this.optionalOption(command, "target"));
+    if (this.metricSource(command, target) === "history") {
+      await this.executeHistoryMetrics(command, target, configuration);
+      return 0;
+    }
     const mode = this.sessionMode(command);
     const session = await this.createSession(configuration, target, mode);
     this.activeSession = session;
@@ -5184,23 +5495,61 @@ var TelemetryCli = class {
       }
     }
   }
+  /**
+   * Which store answers a metric command. `history` is the projector's
+   * pre-aggregated buckets (history.db, current whenever the app runs with
+   * ingest-time extraction off); `legacy` is the collector's own rollups in
+   * telemetry.db. `auto` prefers history.db when it exists beside the target —
+   * since ingestion moved to the projector the legacy rollups stopped
+   * advancing, so answering from them silently reports stale gaps.
+   */
+  metricSource(command, target) {
+    if (command.kind !== "metrics-query" && command.kind !== "metrics-graph") return "legacy";
+    const requested = this.optionalOption(command, "source") ?? "auto";
+    if (requested === "history" || requested === "legacy") return requested;
+    if (requested !== "auto") {
+      throw new TelemetryCliUsageError("--source must be auto, history, or legacy");
+    }
+    return HistoryMetricReader.exists(historyDatabasePath(target)) ? "history" : "legacy";
+  }
+  async executeHistoryMetrics(command, target, configuration) {
+    const databasePath = historyDatabasePath(target);
+    if (!HistoryMetricReader.exists(databasePath)) {
+      throw new TelemetryCliUsageError(`No projector history store at ${databasePath}`);
+    }
+    const reader = HistoryMetricReader.open(databasePath, configuration.metrics);
+    try {
+      const run = async (query) => reader.metrics(query, target.targetId);
+      if (command.kind === "metrics-graph") {
+        await this.metricGraph(command, target, run);
+      } else {
+        await this.metricQuery(command, target, run);
+      }
+    } finally {
+      reader.close();
+    }
+  }
   async executeCommand(command, target, session) {
     if (command.kind === "timeline-query") {
       await this.timelineQuery(command, target, session);
       return;
     }
     if (command.kind === "metrics-query") {
-      await this.metricQuery(command, target, session);
+      await this.metricQuery(command, target, (query) => session.metrics(query));
       return;
     }
     if (command.kind === "metrics-graph") {
-      await this.metricGraph(command, target, session);
+      await this.metricGraph(command, target, (query) => session.metrics(query));
       return;
     }
     if (command.kind === "sqlite-query") {
       await this.sqliteQuery(command, target, session);
       return;
     }
+    if (command.kind === "sqlite-compact") {
+      await this.sqliteCompact(command, target, session);
+      return;
+    }
     if (command.kind === "sqlite-migration-status" || command.kind === "sqlite-migration-up") {
       await this.sqliteMigration(command, target, session);
       return;
@@ -5230,8 +5579,8 @@ var TelemetryCli = class {
     const output = this.formatter.timeline(result.value, format, this.timezoneOption(command));
     this.writeBounded(output, target.query.maxResponseBytes);
   }
-  async metricQuery(command, target, session) {
-    const result = await session.metrics(this.metricQueryInput(command, target));
+  async metricQuery(command, target, runMetrics) {
+    const result = await runMetrics(this.metricQueryInput(command, target));
     if (!result.ok) {
       throw new Error(`${result.error.kind}: ${result.error.message}`);
     }
@@ -5242,12 +5591,12 @@ var TelemetryCli = class {
     );
     this.writeBounded(output, target.query.maxResponseBytes);
   }
-  async metricGraph(command, target, session) {
+  async metricGraph(command, target, runMetrics) {
     const measurements = this.options(command, "measurement");
     if (measurements.length !== 1) {
       throw new TelemetryCliUsageError("metrics graph requires exactly one --measurement");
     }
-    const result = await session.metrics(this.metricQueryInput(command, target));
+    const result = await runMetrics(this.metricQueryInput(command, target));
     if (!result.ok) {
       throw new Error(`${result.error.kind}: ${result.error.message}`);
     }
@@ -5298,6 +5647,14 @@ var TelemetryCli = class {
     }
     this.writeBounded(this.formatter.migrations(result, format), target.query.maxResponseBytes);
   }
+  async sqliteCompact(command, target, session) {
+    const format = this.optionalOption(command, "format") ?? "table";
+    if (format !== "table" && format !== "json") {
+      throw new TelemetryCliUsageError("Compaction format must be table or json");
+    }
+    const result = await session.compact();
+    this.writeBounded(this.formatter.compaction(result, format), target.query.maxResponseBytes);
+  }
   metricQueryInput(command, target) {
     const measurements = this.options(command, "measurement");
     if (measurements.length === 0) {
@@ -5332,7 +5689,7 @@ var TelemetryCli = class {
     return target;
   }
   sessionMode(command) {
-    return command.kind === "sqlite-migration-status" || command.kind === "sqlite-migration-up" ? "maintenance" : "query";
+    return command.kind === "sqlite-compact" || command.kind === "sqlite-migration-status" || command.kind === "sqlite-migration-up" ? "maintenance" : "query";
   }
   structuredFormat(command) {
     const value = this.optionalOption(command, "format") ?? "table";
@@ -5499,9 +5856,10 @@ var TelemetryCli = class {
   help() {
     return `Usage:
   telemetry timeline query --config FILE --from TIME --to TIME [filters] [--format table|json|jsonl|csv]
-  telemetry metrics query --config FILE --metric NAME --measurement NAME --resolution DURATION|auto --from TIME --to TIME [--where KEY=VALUE]
-  telemetry metrics graph --config FILE --metric NAME --measurement NAME --resolution DURATION|auto --from TIME --to TIME [--type line|bar|stacked-bar] [--format terminal|svg|html]
+  telemetry metrics query --config FILE --metric NAME --measurement NAME --resolution DURATION|auto --from TIME --to TIME [--where KEY=VALUE] [--source auto|history|legacy]
+  telemetry metrics graph --config FILE --metric NAME --measurement NAME --resolution DURATION|auto --from TIME --to TIME [--type line|bar|stacked-bar] [--format terminal|svg|html] [--source auto|history|legacy]
   telemetry sqlite query --config FILE --sql SQL [--param NAME=VALUE] [--format table|json|jsonl|csv]
+  telemetry sqlite compact --config FILE [--format table|json]
   telemetry sqlite migration status --config FILE [--format table|json]
   telemetry sqlite migration up --config FILE [--format table|json]