@noego/telemetry 0.0.5 → 0.1.0

package/dist/projector/index.cjs

@@ -0,0 +1,1370 @@
+/* @noego/telemetry */
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/projector/index.ts
+var projector_exports = {};
+__export(projector_exports, {
+  TraceProjector: () => TraceProjector,
+  createTraceProjectorProcess: () => createTraceProjectorProcess,
+  detectSourceReset: () => detectSourceReset,
+  eventSelectorMatches: () => eventSelectorMatches,
+  metricDefinitionToTraceProjection: () => metricDefinitionToTraceProjection,
+  metricDefinitionsToTraceProjections: () => metricDefinitionsToTraceProjections,
+  validateTraceProjection: () => validateTraceProjection
+});
+module.exports = __toCommonJS(projector_exports);
+
+// src/projector/trace_projection.types.ts
+var NAME_PATTERN = /^[a-z][a-z0-9_.-]*$/;
+function validateTraceProjection(projection) {
+  if (!NAME_PATTERN.test(projection.name)) {
+    throw new Error(`TraceProjection: invalid name '${projection.name}'`);
+  }
+  if (!Number.isSafeInteger(projection.version) || projection.version < 1) {
+    throw new Error(`TraceProjection '${projection.name}': version must be a positive integer`);
+  }
+  if (typeof projection.event !== "string" || projection.event.trim().length === 0) {
+    throw new Error(`TraceProjection '${projection.name}': event selector is required`);
+  }
+  if (projection.resolutions.length === 0) {
+    throw new Error(`TraceProjection '${projection.name}': at least one resolution is required`);
+  }
+  for (const resolution of projection.resolutions) {
+    if (!Number.isSafeInteger(resolution) || resolution < 1) {
+      throw new Error(`TraceProjection '${projection.name}': resolutions must be positive integers`);
+    }
+  }
+  for (const measurement of projection.measurements) {
+    if (typeof measurement.field !== "string" || measurement.field.trim().length === 0) {
+      throw new Error(`TraceProjection '${projection.name}': measurement field is required`);
+    }
+    if (measurement.aggregates.length === 0) {
+      throw new Error(
+        `TraceProjection '${projection.name}': measurement '${measurement.field}' needs at least one aggregate`
+      );
+    }
+  }
+  const dimensions = projection.groupBy ?? [];
+  if (new Set(dimensions).size !== dimensions.length) {
+    throw new Error(`TraceProjection '${projection.name}': duplicate groupBy dimension`);
+  }
+}
+
+// src/projector/trace_projector.ts
+var SCAN_PROGRESS_KEY = "__scan__";
+var OVERFLOW_DIMENSIONS = Object.freeze({ __overflow__: "other" });
+var TraceProjector = class {
+  source;
+  db;
+  projections;
+  pageSize;
+  now;
+  constructor(options) {
+    this.source = options.source;
+    this.db = options.destination;
+    this.projections = options.projections;
+    this.pageSize = Math.max(1, options.pageSize ?? 500);
+    this.now = options.now ?? Date.now;
+    for (const projection of this.projections) {
+      validateTraceProjection(projection);
+    }
+    this.initializeSchema();
+    this.registerDefinitions();
+  }
+  /**
+   * Drains all unprojected raw traces, page by page, committing progress per
+   * page.
+   *
+   * The durable cursor is a source rowid, so it is only meaningful against
+   * the store file it was taken from. When the source describes itself, a
+   * cursor whose epoch differs from the store's — or that lies beyond the
+   * store's newest row — belongs to a store that has since been recreated
+   * (boot reset, manual deletion) and is discarded, restarting the scan at
+   * row 0. 2026-09-03: the live projector sat at rowid 22.6M over a rebuilt
+   * store holding rows 1–440k, reported "caught up" every minute, and wrote
+   * no buckets for ten hours.
+   */
+  runOnce() {
+    const description = this.source.describe?.() ?? null;
+    const progress = this.loadProgress();
+    const sourceReset = detectSourceReset(progress, description);
+    let cursor = sourceReset === null ? progress : null;
+    const result = {
+      pages: 0,
+      eventsRead: 0,
+      selectorMatches: 0,
+      bucketsUpdated: 0,
+      failures: 0,
+      progress: "caught-up-no-new-source",
+      cursorRowId: cursor?.rowId ?? null,
+      sourceHighRowId: description?.highRowId ?? null,
+      sourceEpoch: description?.storeEpoch ?? null,
+      sourceReset
+    };
+    for (; ; ) {
+      const page = this.source.readAfter(cursor, { limit: this.pageSize });
+      if (page.events.length === 0) break;
+      const apply = this.db.transaction(() => {
+        for (const event of page.events) {
+          let matched = false;
+          for (const projection of this.projections) {
+            if (!this.matches(projection, event)) continue;
+            matched = true;
+            const outcome = this.applyEvent(projection, event);
+            result.bucketsUpdated += outcome.bucketsUpdated;
+            result.failures += outcome.failures;
+          }
+          if (matched) result.selectorMatches += 1;
+        }
+        this.saveProgress(page.cursor, description?.storeEpoch ?? progress?.storeEpoch ?? null);
+      });
+      apply();
+      cursor = page.cursor;
+      result.pages += 1;
+      result.eventsRead += page.events.length;
+    }
+    if (sourceReset !== null && result.pages === 0) {
+      this.saveProgress({ rowId: 0 }, description?.storeEpoch ?? null);
+    }
+    result.cursorRowId = cursor?.rowId ?? (sourceReset !== null ? 0 : null);
+    result.progress = classifyProgress(result);
+    return result;
+  }
+  /** Newest completed bucket start per projection at the given resolution — the freshness signal. */
+  newestBucketStartMs(resolutionMs) {
+    const row = this.db.prepare(
+      "SELECT MAX(bucket_start_ms) AS newest FROM trace_metric_buckets WHERE resolution_ms = ?"
+    ).get(resolutionMs);
+    return row.newest;
+  }
+  /**
+   * Rebuilds one projection's derived buckets for an occurrence-time range
+   * from retained raw traces (spec 04 §14–15): clears coverage for the range,
+   * then reprojects every retained matching event. Uses the same extraction
+   * code as forward projection; does not touch the forward scan cursor.
+   */
+  backfill(options) {
+    const projection = this.projections.find(
+      (candidate) => candidate.name === options.projection && candidate.version === options.version
+    );
+    if (!projection) {
+      throw new Error(`TraceProjector: unknown projection ${options.projection}@${options.version}`);
+    }
+    const result = { pages: 0, eventsRead: 0, bucketsUpdated: 0, failures: 0 };
+    const run = this.db.transaction(() => {
+      for (const resolution of projection.resolutions) {
+        const firstBucket = bucketStart(options.fromOccurredAtMs, resolution);
+        this.db.prepare(`
+          DELETE FROM trace_metric_buckets
+          WHERE projection_name = ? AND projection_version = ? AND resolution_ms = ?
+            AND bucket_start_ms >= ? AND bucket_start_ms <= ?
+        `).run(projection.name, projection.version, resolution, firstBucket, options.toOccurredAtMs);
+      }
+      let cursor = null;
+      for (; ; ) {
+        const page = this.source.readAfter(cursor, {
+          limit: this.pageSize,
+          toOccurredAtMs: options.toOccurredAtMs
+        });
+        if (page.events.length === 0) break;
+        for (const event of page.events) {
+          if (event.occurredAtMs < options.fromOccurredAtMs) continue;
+          if (!this.matches(projection, event)) continue;
+          const outcome = this.applyEvent(projection, event);
+          result.bucketsUpdated += outcome.bucketsUpdated;
+          result.failures += outcome.failures;
+          result.eventsRead += 1;
+        }
+        cursor = page.cursor;
+        result.pages += 1;
+      }
+    });
+    run();
+    return result;
+  }
+  /** Historical bucket query with explicit projection/version/resolution. */
+  query(query) {
+    const clauses = [
+      "projection_name = @projection",
+      "projection_version = @version",
+      "resolution_ms = @resolutionMs"
+    ];
+    const params = {
+      projection: query.projection,
+      version: query.version,
+      resolutionMs: query.resolutionMs
+    };
+    if (query.fromMs !== void 0) {
+      clauses.push("bucket_start_ms >= @fromMs");
+      params.fromMs = query.fromMs;
+    }
+    if (query.toMs !== void 0) {
+      clauses.push("bucket_start_ms <= @toMs");
+      params.toMs = query.toMs;
+    }
+    if (query.dimensions !== void 0) {
+      clauses.push("dimension_key = @dimensionKey");
+      params.dimensionKey = dimensionKey(query.dimensions);
+    }
+    const rows = this.db.prepare(`
+      SELECT * FROM trace_metric_buckets
+      WHERE ${clauses.join(" AND ")}
+      ORDER BY bucket_start_ms, dimension_key
+    `).all(params);
+    return rows.map((row) => {
+      const values = JSON.parse(row.values_json);
+      const averages = {};
+      for (const [field, state] of Object.entries(values)) {
+        if (state.count > 0) averages[field] = state.sum / state.count;
+      }
+      return {
+        projection: row.projection_name,
+        version: row.projection_version,
+        resolutionMs: row.resolution_ms,
+        bucketStartMs: row.bucket_start_ms,
+        dimensions: JSON.parse(row.dimensions_json),
+        count: row.count,
+        values,
+        averages
+      };
+    });
+  }
+  /** Bounded projection failures, newest first. */
+  failures(limit = 100) {
+    const rows = this.db.prepare(`
+      SELECT projection_name, projection_version, trace_id, reason
+      FROM trace_projection_failures ORDER BY recorded_at_ms DESC LIMIT ?
+    `).all(Math.max(1, limit));
+    return rows.map((row) => ({
+      projection: row.projection_name,
+      version: row.projection_version,
+      traceId: row.trace_id,
+      reason: row.reason
+    }));
+  }
+  matches(projection, event) {
+    if (!eventSelectorMatches(projection.event, event.event)) return false;
+    if (projection.source !== void 0 && event.source !== projection.source) return false;
+    return true;
+  }
+  applyEvent(projection, event) {
+    const context = event.context ?? {};
+    let dimensions = {};
+    for (const field of projection.groupBy ?? []) {
+      const value = context[field];
+      dimensions[field] = value === void 0 || value === null ? "" : String(value);
+    }
+    const measured = {};
+    for (const measurement of projection.measurements) {
+      const value = context[measurement.field];
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        if ((projection.missingField ?? "record-failure") === "skip") {
+          continue;
+        }
+        this.recordFailure(projection, event, `measurement field '${measurement.field}' is not a finite number`);
+        return { bucketsUpdated: 0, failures: 1 };
+      }
+      measured[measurement.field] = value;
+    }
+    if (!this.admitDimensions(projection, dimensions)) {
+      if ((projection.cardinality?.overflow ?? "reject") === "other") {
+        dimensions = { ...OVERFLOW_DIMENSIONS };
+      } else {
+        this.recordFailure(projection, event, "dimension cardinality limit exceeded");
+        return { bucketsUpdated: 0, failures: 1 };
+      }
+    }
+    let bucketsUpdated = 0;
+    for (const resolution of projection.resolutions) {
+      this.updateBucket(projection, resolution, bucketStart(event.occurredAtMs, resolution), dimensions, measured);
+      bucketsUpdated += 1;
+    }
+    return { bucketsUpdated, failures: 0 };
+  }
+  admitDimensions(projection, dimensions) {
+    const limit = projection.cardinality?.maxDimensionKeys;
+    if (limit === void 0) return true;
+    const key = dimensionKey(dimensions);
+    const known = this.db.prepare(`
+      SELECT 1 FROM trace_metric_buckets
+      WHERE projection_name = ? AND projection_version = ? AND dimension_key = ?
+      LIMIT 1
+    `).get(projection.name, projection.version, key);
+    if (known) return true;
+    const row = this.db.prepare(`
+      SELECT COUNT(DISTINCT dimension_key) AS n FROM trace_metric_buckets
+      WHERE projection_name = ? AND projection_version = ?
+    `).get(projection.name, projection.version);
+    return row.n < limit;
+  }
+  updateBucket(projection, resolutionMs, bucketStartMs, dimensions, measured) {
+    const key = dimensionKey(dimensions);
+    const existing = this.db.prepare(`
+      SELECT count, values_json FROM trace_metric_buckets
+      WHERE projection_name = ? AND projection_version = ? AND resolution_ms = ?
+        AND bucket_start_ms = ? AND dimension_key = ?
+    `).get(projection.name, projection.version, resolutionMs, bucketStartMs, key);
+    const values = existing ? JSON.parse(existing.values_json) : {};
+    for (const [field, value] of Object.entries(measured)) {
+      const state = values[field] ?? {
+        count: 0,
+        sum: 0,
+        min: Number.POSITIVE_INFINITY,
+        max: Number.NEGATIVE_INFINITY,
+        last: Number.NaN
+      };
+      state.count += 1;
+      state.sum += value;
+      state.min = Math.min(state.min, value);
+      state.max = Math.max(state.max, value);
+      state.last = value;
+      values[field] = state;
+    }
+    this.db.prepare(`
+      INSERT INTO trace_metric_buckets (
+        projection_name, projection_version, resolution_ms, bucket_start_ms,
+        dimension_key, dimensions_json, count, values_json, updated_at_ms
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT (projection_name, projection_version, resolution_ms, bucket_start_ms, dimension_key)
+      DO UPDATE SET count = excluded.count, values_json = excluded.values_json, updated_at_ms = excluded.updated_at_ms
+    `).run(
+      projection.name,
+      projection.version,
+      resolutionMs,
+      bucketStartMs,
+      key,
+      JSON.stringify(dimensions),
+      (existing?.count ?? 0) + 1,
+      JSON.stringify(values),
+      this.now()
+    );
+  }
+  recordFailure(projection, event, reason) {
+    this.db.prepare(`
+      INSERT INTO trace_projection_failures (
+        projection_name, projection_version, trace_id, reason, occurred_at_ms, recorded_at_ms
+      ) VALUES (?, ?, ?, ?, ?, ?)
+    `).run(projection.name, projection.version, event.id, reason, event.occurredAtMs, this.now());
+  }
+  loadProgress() {
+    const row = this.db.prepare(
+      "SELECT cursor_json FROM trace_projection_progress WHERE progress_key = ?"
+    ).get(SCAN_PROGRESS_KEY);
+    if (!row) return null;
+    const parsed = JSON.parse(row.cursor_json);
+    return { rowId: parsed.rowId, storeEpoch: parsed.storeEpoch ?? null };
+  }
+  saveProgress(cursor, storeEpoch) {
+    if (cursor === null) return;
+    const progress = { rowId: cursor.rowId, storeEpoch };
+    this.db.prepare(`
+      INSERT INTO trace_projection_progress (progress_key, cursor_json, updated_at_ms)
+      VALUES (?, ?, ?)
+      ON CONFLICT (progress_key) DO UPDATE SET cursor_json = excluded.cursor_json, updated_at_ms = excluded.updated_at_ms
+    `).run(SCAN_PROGRESS_KEY, JSON.stringify(progress), this.now());
+  }
+  registerDefinitions() {
+    for (const projection of this.projections) {
+      const definitionJson = JSON.stringify(projection);
+      const existing = this.db.prepare(`
+        SELECT definition_json FROM trace_projection_definitions
+        WHERE projection_name = ? AND projection_version = ?
+      `).get(projection.name, projection.version);
+      if (existing === void 0) {
+        this.db.prepare(`
+          INSERT INTO trace_projection_definitions (projection_name, projection_version, definition_json, registered_at_ms)
+          VALUES (?, ?, ?, ?)
+        `).run(projection.name, projection.version, definitionJson, this.now());
+      } else if (existing.definition_json !== definitionJson) {
+        throw new Error(
+          `TraceProjector: projection ${projection.name}@${projection.version} differs from its registered definition; bump the version`
+        );
+      }
+    }
+  }
+  initializeSchema() {
+    this.db.pragma("journal_mode = WAL");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS trace_projection_definitions (
+        projection_name TEXT NOT NULL,
+        projection_version INTEGER NOT NULL,
+        definition_json TEXT NOT NULL,
+        registered_at_ms INTEGER NOT NULL,
+        PRIMARY KEY (projection_name, projection_version)
+      );
+
+      CREATE TABLE IF NOT EXISTS trace_projection_progress (
+        progress_key TEXT NOT NULL PRIMARY KEY,
+        cursor_json TEXT NOT NULL,
+        updated_at_ms INTEGER NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS trace_metric_buckets (
+        projection_name TEXT NOT NULL,
+        projection_version INTEGER NOT NULL,
+        resolution_ms INTEGER NOT NULL,
+        bucket_start_ms INTEGER NOT NULL,
+        dimension_key TEXT NOT NULL,
+        dimensions_json TEXT NOT NULL,
+        count INTEGER NOT NULL,
+        values_json TEXT NOT NULL,
+        updated_at_ms INTEGER NOT NULL,
+        PRIMARY KEY (projection_name, projection_version, resolution_ms, bucket_start_ms, dimension_key)
+      );
+
+      CREATE INDEX IF NOT EXISTS trace_metric_buckets_time_idx
+        ON trace_metric_buckets (projection_name, projection_version, resolution_ms, bucket_start_ms);
+
+      CREATE TABLE IF NOT EXISTS trace_projection_failures (
+        projection_name TEXT NOT NULL,
+        projection_version INTEGER NOT NULL,
+        trace_id TEXT NOT NULL,
+        reason TEXT NOT NULL,
+        occurred_at_ms INTEGER NOT NULL,
+        recorded_at_ms INTEGER NOT NULL
+      );
+    `);
+  }
+};
+function eventSelectorMatches(selector, eventName) {
+  if (selector === eventName) return true;
+  if (!selector.includes("*")) return false;
+  const selectorParts = selector.split(".");
+  const eventParts = eventName.split(".");
+  for (let i = 0; i < selectorParts.length; i++) {
+    const part = selectorParts[i];
+    if (part === "**") {
+      return i === selectorParts.length - 1;
+    }
+    if (i >= eventParts.length) return false;
+    if (part !== "*" && part !== eventParts[i]) return false;
+  }
+  return selectorParts.length === eventParts.length;
+}
+function bucketStart(occurredAtMs, resolutionMs) {
+  return occurredAtMs - occurredAtMs % resolutionMs;
+}
+function detectSourceReset(progress, description) {
+  if (progress === null || description === null) return null;
+  if (progress.storeEpoch !== null && progress.storeEpoch !== description.storeEpoch) {
+    return "store-epoch-changed";
+  }
+  if (progress.rowId > description.highRowId) return "cursor-beyond-source";
+  return null;
+}
+function classifyProgress(result) {
+  if (result.bucketsUpdated > 0) return "buckets-updated";
+  if (result.eventsRead === 0) return "caught-up-no-new-source";
+  if (result.selectorMatches === 0) return "new-source-no-selector-match";
+  return "matching-source-no-bucket";
+}
+function dimensionKey(dimensions) {
+  const sorted = Object.keys(dimensions).sort().map((key) => [key, dimensions[key]]);
+  return JSON.stringify(sorted);
+}
+
+// src/projector/trace_projector_process.ts
+var import_node_fs2 = require("fs");
+var import_node_path2 = __toESM(require("path"), 1);
+var import_better_sqlite3 = __toESM(require("better-sqlite3"), 1);
+var import_sqlite = require("@noego/trace/sqlite");
+
+// src/platform/node/telemetry_configuration_parser.ts
+var import_node_path = require("path");
+var import_node_fs = require("fs");
+var import_js_yaml = require("js-yaml");
+
+// src/core/metric_definition_contract.ts
+var MetricDefinitionContract = class {
+  normalize(definition) {
+    const parsedSelector = this.parseSelector(definition.selector);
+    if (!parsedSelector.ok) {
+      return parsedSelector;
+    }
+    const bracketGroupBy = parsedSelector.value.groupBy;
+    const configuredGroupBy = definition.groupBy;
+    const bothSpecifyDifferentGrouping = bracketGroupBy.length > 0 && configuredGroupBy.length > 0 && bracketGroupBy.join(".") !== configuredGroupBy.join(".");
+    if (bothSpecifyDifferentGrouping) {
+      return { ok: false, error: `Metric ${definition.name} has conflicting selector and groupBy declarations` };
+    }
+    const groupBy = configuredGroupBy.length > 0 ? configuredGroupBy : bracketGroupBy;
+    const basicError = this.validateBasic(definition, parsedSelector.value.selector, groupBy);
+    if (basicError !== null) {
+      return { ok: false, error: basicError };
+    }
+    if (parsedSelector.value.wildcardUngrouped && definition.measurements.some((measurement) => measurement.kind !== "count")) {
+      return {
+        ok: false,
+        error: `Metric ${definition.name} uses [*] and may only declare count`
+      };
+    }
+    return {
+      ok: true,
+      value: Object.freeze({
+        ...definition,
+        selector: parsedSelector.value.selector,
+        groupBy: Object.freeze([...groupBy]),
+        resolutionsMs: Object.freeze([...definition.resolutionsMs].sort((left, right) => left - right)),
+        measurements: Object.freeze([...definition.measurements]),
+        targetIds: Object.freeze([...definition.targetIds]),
+        cardinality: Object.freeze({ ...definition.cardinality })
+      })
+    };
+  }
+  matches(selector, label) {
+    const selectorSegments = selector.split(".");
+    const labelSegments = label.split(".");
+    return this.matchSegments(selectorSegments, labelSegments, 0, 0);
+  }
+  parseSelector(selector) {
+    if (selector.startsWith("[")) {
+      return { ok: false, error: "A metric selector cannot omit its event label or glob" };
+    }
+    const bracketStart = selector.lastIndexOf("[");
+    if (bracketStart < 0) {
+      return { ok: true, value: { selector, groupBy: [], wildcardUngrouped: false } };
+    }
+    if (!selector.endsWith("]")) {
+      return { ok: false, error: `Invalid metric selector ${selector}` };
+    }
+    const eventSelector = selector.slice(0, bracketStart);
+    const bracket = selector.slice(bracketStart + 1, -1).trim();
+    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,
+        wildcardUngrouped: bracket === "*"
+      }
+    };
+  }
+  validateBasic(definition, selector, groupBy) {
+    if (!/^[A-Za-z0-9_*][A-Za-z0-9_.:*\-]*$/.test(selector)) {
+      return `Metric ${definition.name} has an invalid selector`;
+    }
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(definition.name)) {
+      return `Metric name ${definition.name} is invalid`;
+    }
+    if (!Number.isInteger(definition.version) || definition.version <= 0) {
+      return `Metric ${definition.name} must have a positive integer version`;
+    }
+    if (definition.measurements.length === 0) {
+      return `Metric ${definition.name} must declare at least one measurement`;
+    }
+    const invalidResolution = definition.resolutionsMs.some(
+      (resolution) => !Number.isInteger(resolution) || resolution <= 0
+    );
+    const duplicateResolution = new Set(definition.resolutionsMs).size !== definition.resolutionsMs.length;
+    if (invalidResolution || duplicateResolution || definition.resolutionsMs.length === 0) {
+      return `Metric ${definition.name} has invalid or duplicate resolutions`;
+    }
+    const missingCardinality = groupBy.find((field) => definition.cardinality[field] === void 0);
+    if (missingCardinality) {
+      return `Metric ${definition.name} is missing cardinality policy for ${missingCardinality}`;
+    }
+    const invalidCardinality = Object.values(definition.cardinality).some(
+      (rule) => !Number.isInteger(rule.maxValuesPerBucket) || rule.maxValuesPerBucket <= 0
+    );
+    if (invalidCardinality) {
+      return `Metric ${definition.name} has an invalid cardinality limit`;
+    }
+    return null;
+  }
+  matchSegments(selector, label, selectorIndex, labelIndex) {
+    if (selectorIndex === selector.length) {
+      return labelIndex === label.length;
+    }
+    const segment = selector[selectorIndex];
+    if (segment === "**") {
+      if (selectorIndex === selector.length - 1) {
+        return true;
+      }
+      for (let next = labelIndex; next <= label.length; next += 1) {
+        if (this.matchSegments(selector, label, selectorIndex + 1, next)) {
+          return true;
+        }
+      }
+      return false;
+    }
+    if (labelIndex >= label.length) {
+      return false;
+    }
+    const segmentMatches = segment === "*" || segment === label[labelIndex];
+    return segmentMatches && this.matchSegments(selector, label, selectorIndex + 1, labelIndex + 1);
+  }
+};
+
+// src/core/helper/canonical_json.ts
+var UTF8_ENCODER = new TextEncoder();
+function compareCanonicalKeys(left, right) {
+  if (left === right) return 0;
+  if (/^[\x00-\x7f]*$/.test(left) && /^[\x00-\x7f]*$/.test(right)) {
+    return left < right ? -1 : 1;
+  }
+  const leftBytes = UTF8_ENCODER.encode(left);
+  const rightBytes = UTF8_ENCODER.encode(right);
+  const length = Math.min(leftBytes.length, rightBytes.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (leftBytes[index] ?? 0) - (rightBytes[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return leftBytes.length - rightBytes.length;
+}
+function canonicalJson(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("Canonical telemetry JSON cannot encode a non-finite number");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => canonicalJson(item));
+    return `[${items.join(",")}]`;
+  }
+  if (typeof value !== "object") {
+    throw new Error(`Canonical telemetry JSON cannot encode ${typeof value}`);
+  }
+  const entries = Object.entries(value).sort(([left], [right]) => compareCanonicalKeys(left, right));
+  const properties = entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`);
+  return `{${properties.join(",")}}`;
+}
+function telemetryChecksum(value) {
+  const bytes = new TextEncoder().encode(canonicalJson(value));
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (const byte of bytes) {
+    hash ^= BigInt(byte);
+    hash = BigInt.asUintN(64, hash * prime);
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+// src/storage/helper/sqlite_table_names.ts
+var SQLITE_LOGICAL_TABLE_NAMES = [
+  "rawEvents",
+  "batchAcknowledgements",
+  "ingestWatermarks",
+  "metricDefinitions",
+  "metricSamples",
+  "metricRollups",
+  "rollupCompletions",
+  "extractionFailures",
+  "maintenanceRuns",
+  "readerLeases",
+  "committedDropCounters",
+  "migrationHistory"
+];
+var SQLITE_DEFAULT_TABLE_NAMES = Object.freeze({
+  rawEvents: "raw_events",
+  batchAcknowledgements: "batch_acknowledgements",
+  ingestWatermarks: "ingest_watermarks",
+  metricDefinitions: "metric_definitions",
+  metricSamples: "metric_samples",
+  metricRollups: "metric_rollups",
+  rollupCompletions: "rollup_completions",
+  extractionFailures: "extraction_failures",
+  maintenanceRuns: "maintenance_runs",
+  readerLeases: "reader_leases",
+  committedDropCounters: "committed_drop_counters",
+  migrationHistory: "migration_history"
+});
+var SQLITE_SCHEMA_MANIFEST_TABLE = "telemetry_schema_manifest";
+
+// src/storage/telemetry_table_map.ts
+var TelemetryTableMap = class _TelemetryTableMap {
+  constructor(mapping, checksum) {
+    this.mapping = mapping;
+    this.checksum = checksum;
+    this.tokenMap = Object.freeze({
+      ...mapping,
+      rawEventsOccurredIndex: this.indexName(mapping.rawEvents, "occurred"),
+      rawEventsConversationIndex: this.indexName(mapping.rawEvents, "conversation"),
+      rawEventsLabelIndex: this.indexName(mapping.rawEvents, "label"),
+      rawEventsLevelIndex: this.indexName(mapping.rawEvents, "level"),
+      metricSamplesTimeIndex: this.indexName(mapping.metricSamples, "time"),
+      metricSamplesEventIndex: this.indexName(mapping.metricSamples, "event"),
+      metricRollupsTimeIndex: this.indexName(mapping.metricRollups, "time")
+    });
+  }
+  mapping;
+  checksum;
+  tokenMap;
+  static create(configuration) {
+    const prefixError = _TelemetryTableMap.validateOptionalPrefix(configuration.tablePrefix);
+    if (prefixError !== null) {
+      return { ok: false, error: prefixError };
+    }
+    const entries = SQLITE_LOGICAL_TABLE_NAMES.map((logicalName) => {
+      const override = configuration.tables[logicalName];
+      const defaultName = SQLITE_DEFAULT_TABLE_NAMES[logicalName];
+      const physicalName = override ?? (configuration.tablePrefix === null ? defaultName : `${configuration.tablePrefix}${defaultName}`);
+      return [logicalName, physicalName];
+    });
+    for (const [logicalName, physicalName] of entries) {
+      const identifierError = _TelemetryTableMap.validateIdentifier(physicalName);
+      if (identifierError !== null) {
+        return { ok: false, error: `${logicalName}: ${identifierError}` };
+      }
+      if (physicalName.toLowerCase() === SQLITE_SCHEMA_MANIFEST_TABLE) {
+        return { ok: false, error: `${logicalName} cannot use the fixed schema manifest name` };
+      }
+    }
+    const foldedNames = entries.map(([, physicalName]) => physicalName.toLowerCase());
+    if (new Set(foldedNames).size !== foldedNames.length) {
+      return { ok: false, error: "Resolved telemetry table names must be unique after case folding" };
+    }
+    const mapping = Object.freeze(Object.fromEntries(entries));
+    const checksum = telemetryChecksum(mapping);
+    return { ok: true, value: new _TelemetryTableMap(mapping, checksum) };
+  }
+  physical(logicalName) {
+    return this.mapping[logicalName];
+  }
+  quoted(logicalName) {
+    return this.quote(this.mapping[logicalName]);
+  }
+  manifestMapping() {
+    return this.mapping;
+  }
+  substitute(sql) {
+    const unknownTokens = [];
+    const substituted = sql.replace(/\{\{([A-Za-z][A-Za-z0-9]*)\}\}/g, (_match, token) => {
+      const identifier = this.tokenMap[token];
+      if (identifier === void 0) {
+        unknownTokens.push(token);
+        return `{{${token}}}`;
+      }
+      return this.quote(identifier);
+    });
+    if (unknownTokens.length > 0 || substituted.includes("{{")) {
+      return {
+        ok: false,
+        error: `Unknown telemetry migration identifier token(s): ${unknownTokens.join(", ") || "malformed token"}`
+      };
+    }
+    return { ok: true, value: substituted };
+  }
+  quote(identifier) {
+    return `"${identifier.replaceAll('"', '""')}"`;
+  }
+  indexName(tableName, purpose) {
+    const raw = `${tableName}_${purpose}_idx`;
+    if (raw.length <= 63) {
+      return raw;
+    }
+    const suffix = telemetryChecksum(raw).slice(0, 8);
+    return `${raw.slice(0, 54)}_${suffix}`;
+  }
+  static validateOptionalPrefix(prefix) {
+    if (prefix === null) {
+      return null;
+    }
+    return this.validateIdentifier(prefix);
+  }
+  static validateIdentifier(identifier) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+      return `Invalid SQLite identifier ${identifier}`;
+    }
+    if (identifier.length > 63) {
+      return `SQLite identifier ${identifier} exceeds 63 characters`;
+    }
+    if (identifier.toLowerCase().startsWith("sqlite_")) {
+      return `SQLite identifier ${identifier} uses the reserved sqlite_ prefix`;
+    }
+    return null;
+  }
+};
+
+// src/platform/node/helper/telemetry_duration_parser.ts
+var TelemetryDurationParser = class _TelemetryDurationParser {
+  static MULTIPLIERS = Object.freeze({
+    ms: 1,
+    s: 1e3,
+    m: 6e4,
+    h: 60 * 6e4,
+    d: 24 * 60 * 6e4,
+    w: 7 * 24 * 60 * 6e4,
+    y: 365 * 24 * 60 * 6e4
+  });
+  parse(value, field, allowZero = false) {
+    const match = /^(0|[1-9][0-9]*)(ms|s|m|h|d|w|y)$/.exec(value);
+    if (!match) {
+      throw new Error(`${field} must be an integer duration using ms, s, m, h, d, w, or y`);
+    }
+    const amount = Number(match[1]);
+    const unit = match[2];
+    const milliseconds = amount * _TelemetryDurationParser.MULTIPLIERS[unit];
+    if (!Number.isSafeInteger(milliseconds) || !allowZero && milliseconds <= 0) {
+      throw new Error(`${field} is outside the supported duration range`);
+    }
+    return milliseconds;
+  }
+};
+
+// src/platform/node/schema/telemetry_configuration_schema.ts
+var import_zod = require("zod");
+var DurationSchema = import_zod.z.string().min(1);
+var NonEmptyStringSchema = import_zod.z.string().trim().min(1);
+var StableIdSchema = import_zod.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+var CardinalityRuleSchema = import_zod.z.object({
+  maxValuesPerBucket: import_zod.z.number().int().positive(),
+  overflow: import_zod.z.enum(["other", "drop", "reject"])
+}).strict();
+var MetricMeasurementSchema = import_zod.z.union([
+  import_zod.z.literal("count"),
+  import_zod.z.object({
+    field: import_zod.z.string().min(1),
+    aggregate: import_zod.z.array(import_zod.z.enum(["sum", "min", "max", "last"])).min(1)
+  }).strict()
+]);
+var MetricDefinitionSchema = import_zod.z.object({
+  name: import_zod.z.string().min(1),
+  version: import_zod.z.number().int().positive().optional(),
+  selector: import_zod.z.string().min(1),
+  groupBy: import_zod.z.array(import_zod.z.string().min(1)).optional(),
+  measurements: import_zod.z.array(MetricMeasurementSchema).min(1),
+  cardinality: import_zod.z.record(import_zod.z.string(), CardinalityRuleSchema).optional(),
+  targets: import_zod.z.array(StableIdSchema).min(1).optional(),
+  resolutions: import_zod.z.array(DurationSchema).min(1).optional(),
+  missingField: import_zod.z.enum(["skip", "record-failure"]).optional()
+}).strict();
+var SqliteTablesSchema = import_zod.z.object({
+  rawEvents: NonEmptyStringSchema.optional(),
+  batchAcknowledgements: NonEmptyStringSchema.optional(),
+  ingestWatermarks: NonEmptyStringSchema.optional(),
+  metricDefinitions: NonEmptyStringSchema.optional(),
+  metricSamples: NonEmptyStringSchema.optional(),
+  metricRollups: NonEmptyStringSchema.optional(),
+  rollupCompletions: NonEmptyStringSchema.optional(),
+  extractionFailures: NonEmptyStringSchema.optional(),
+  maintenanceRuns: NonEmptyStringSchema.optional(),
+  readerLeases: NonEmptyStringSchema.optional(),
+  committedDropCounters: NonEmptyStringSchema.optional(),
+  migrationHistory: NonEmptyStringSchema.optional()
+}).strict();
+var SqliteTargetSchema = import_zod.z.object({
+  id: StableIdSchema,
+  transport: import_zod.z.literal("sqlite"),
+  delivery: import_zod.z.enum(["required", "best-effort"]),
+  path: import_zod.z.string().min(1),
+  schema: import_zod.z.object({
+    tablePrefix: NonEmptyStringSchema.nullable().optional(),
+    tables: SqliteTablesSchema.optional()
+  }).strict().optional(),
+  retention: import_zod.z.object({
+    raw: DurationSchema,
+    lateArrival: DurationSchema.optional(),
+    samples: DurationSchema.optional(),
+    levels: import_zod.z.record(import_zod.z.string().min(1), DurationSchema).optional(),
+    rollups: import_zod.z.array(
+      import_zod.z.object({
+        resolution: DurationSchema,
+        retain: DurationSchema
+      }).strict()
+    ).min(1)
+  }).strict(),
+  maintenance: import_zod.z.object({
+    interval: DurationSchema,
+    maxWorkMs: import_zod.z.number().int().positive(),
+    reclaim: import_zod.z.literal("incremental"),
+    maxReclaimPages: import_zod.z.number().int().positive().optional()
+  }).strict(),
+  leaseExpiry: DurationSchema.optional(),
+  query: import_zod.z.object({
+    maxRange: DurationSchema.optional(),
+    maxRows: import_zod.z.number().int().positive().optional(),
+    maxBuckets: import_zod.z.number().int().positive().optional(),
+    maxResponseBytes: import_zod.z.number().int().positive().optional()
+  }).strict().optional()
+}).strict();
+var StorageSchema = import_zod.z.object({
+  defaultTarget: StableIdSchema.nullable().optional(),
+  targets: import_zod.z.array(SqliteTargetSchema).min(1)
+}).strict();
+var TraceSchema = import_zod.z.object({
+  ingestionTransport: import_zod.z.string().min(1).optional(),
+  storage: StorageSchema.optional()
+}).strict();
+var TelemetryConfigurationDocumentSchema = import_zod.z.object({
+  telemetry: import_zod.z.object({
+    version: import_zod.z.literal(1).optional(),
+    role: import_zod.z.enum(["producer", "collector", "combined"]),
+    trace: TraceSchema,
+    metrics: import_zod.z.array(MetricDefinitionSchema).optional(),
+    logs: import_zod.z.object({
+      transport: import_zod.z.literal("console")
+    }).strict().optional()
+  }).strict()
+}).strict();
+
+// src/platform/node/telemetry_configuration_parser.ts
+var DEFAULT_LEASE_EXPIRY = "30s";
+var DEFAULT_QUERY_RANGE = "365d";
+var DEFAULT_QUERY_ROWS = 1e4;
+var DEFAULT_QUERY_BUCKETS = 1e4;
+var DEFAULT_QUERY_BYTES = 5e6;
+var DEFAULT_RECLAIM_PAGES = 100;
+var TelemetryConfigurationError = class extends Error {
+  constructor(message, source) {
+    super(`${source}: ${message}`);
+    this.source = source;
+    this.name = "TelemetryConfigurationError";
+  }
+  source;
+};
+var NodeTelemetryConfigurationParser = class {
+  constructor(durations = new TelemetryDurationParser(), metricContract = new MetricDefinitionContract()) {
+    this.durations = durations;
+    this.metricContract = metricContract;
+  }
+  durations;
+  metricContract;
+  parseFile(configurationPath, options = {}) {
+    const absolutePath = (0, import_node_path.resolve)(configurationPath);
+    let source;
+    try {
+      source = (0, import_node_fs.readFileSync)(absolutePath, "utf8");
+    } catch (cause) {
+      throw new TelemetryConfigurationError(this.errorMessage(cause), absolutePath);
+    }
+    return this.parseYaml(source, {
+      sourceName: options.sourceName ?? absolutePath,
+      storageBaseDirectory: options.storageBaseDirectory ?? (0, import_node_path.dirname)(absolutePath)
+    });
+  }
+  parseYaml(source, options = {}) {
+    const sourceName = options.sourceName ?? "<telemetry-configuration>";
+    let document;
+    try {
+      document = (0, import_js_yaml.load)(source);
+    } catch (cause) {
+      throw new TelemetryConfigurationError(this.errorMessage(cause), sourceName);
+    }
+    const parsed = TelemetryConfigurationDocumentSchema.safeParse(document);
+    if (!parsed.success) {
+      throw new TelemetryConfigurationError(parsed.error.message, sourceName);
+    }
+    try {
+      const baseDirectory = options.storageBaseDirectory === void 0 ? (0, import_node_path.dirname)((0, import_node_path.resolve)(sourceName)) : (0, import_node_path.resolve)(options.storageBaseDirectory);
+      return this.resolveDocument(parsed.data, baseDirectory);
+    } catch (cause) {
+      if (cause instanceof TelemetryConfigurationError) {
+        throw cause;
+      }
+      throw new TelemetryConfigurationError(this.errorMessage(cause), sourceName);
+    }
+  }
+  resolveDocument(document, baseDirectory) {
+    const telemetry = document.telemetry;
+    this.validateRole(telemetry.role, telemetry.trace);
+    const serializedTargets = telemetry.trace.storage?.targets ?? [];
+    const targets = serializedTargets.map(
+      (target, index) => this.resolveTarget(target, baseDirectory, index)
+    );
+    this.validateTargets(telemetry.role, targets, telemetry.trace.storage?.defaultTarget ?? null);
+    const metrics = (telemetry.metrics ?? []).map(
+      (metric, index) => this.resolveMetric(metric, targets, index)
+    );
+    this.validateMetricIdentities(metrics);
+    return Object.freeze({
+      version: telemetry.version ?? 1,
+      role: telemetry.role,
+      ingestionTransport: telemetry.trace.ingestionTransport ?? null,
+      logTransport: telemetry.logs?.transport ?? null,
+      defaultTargetId: telemetry.trace.storage?.defaultTarget ?? null,
+      sqliteTargets: Object.freeze(targets),
+      metrics: Object.freeze(metrics)
+    });
+  }
+  validateRole(role, trace) {
+    const hasIngestion = trace.ingestionTransport !== void 0;
+    const hasStorage = trace.storage !== void 0;
+    if (role === "producer" && (!hasIngestion || hasStorage)) {
+      throw new Error("Producer telemetry requires ingestionTransport and forbids storage");
+    }
+    if (role === "collector" && !hasStorage) {
+      throw new Error("Collector telemetry requires storage targets");
+    }
+    if (role === "combined" && (!hasIngestion || !hasStorage)) {
+      throw new Error("Combined telemetry requires ingestionTransport and storage targets");
+    }
+  }
+  resolveTarget(target, baseDirectory, index) {
+    const field = `telemetry.trace.storage.targets[${index}]`;
+    const rawMs = this.durations.parse(target.retention.raw, `${field}.retention.raw`);
+    const lateArrivalMs = this.durations.parse(
+      target.retention.lateArrival ?? "0ms",
+      `${field}.retention.lateArrival`,
+      true
+    );
+    const samplesMs = target.retention.samples === void 0 ? rawMs + lateArrivalMs : this.durations.parse(target.retention.samples, `${field}.retention.samples`);
+    const levelMs = this.resolveLevelRetention(target.retention.levels, field);
+    const rollups = target.retention.rollups.map(
+      (tier, tierIndex) => Object.freeze({
+        resolutionMs: this.durations.parse(
+          tier.resolution,
+          `${field}.retention.rollups[${tierIndex}].resolution`
+        ),
+        retainMs: this.durations.parse(
+          tier.retain,
+          `${field}.retention.rollups[${tierIndex}].retain`
+        )
+      })
+    );
+    const tables = Object.freeze(
+      Object.fromEntries(
+        Object.entries(target.schema?.tables ?? {}).filter((entry) => entry[1] !== void 0)
+      )
+    );
+    const schema = Object.freeze({
+      tablePrefix: target.schema?.tablePrefix ?? null,
+      tables
+    });
+    const tableMap = TelemetryTableMap.create(schema);
+    if (!tableMap.ok) {
+      throw new Error(`${field}.schema: ${tableMap.error}`);
+    }
+    const resolved = Object.freeze({
+      targetId: target.id,
+      path: (0, import_node_path.resolve)(baseDirectory, target.path),
+      delivery: target.delivery,
+      schema,
+      retention: Object.freeze({
+        rawMs,
+        lateArrivalMs,
+        samplesMs,
+        levelMs,
+        rollups: Object.freeze(rollups)
+      }),
+      maintenance: Object.freeze({
+        intervalMs: this.durations.parse(
+          target.maintenance.interval,
+          `${field}.maintenance.interval`
+        ),
+        maxWorkMs: target.maintenance.maxWorkMs,
+        maxReclaimPages: target.maintenance.maxReclaimPages ?? DEFAULT_RECLAIM_PAGES
+      }),
+      leaseExpiryMs: this.durations.parse(
+        target.leaseExpiry ?? DEFAULT_LEASE_EXPIRY,
+        `${field}.leaseExpiry`
+      ),
+      query: Object.freeze({
+        maxRangeMs: this.durations.parse(
+          target.query?.maxRange ?? DEFAULT_QUERY_RANGE,
+          `${field}.query.maxRange`
+        ),
+        maxRows: target.query?.maxRows ?? DEFAULT_QUERY_ROWS,
+        maxBuckets: target.query?.maxBuckets ?? DEFAULT_QUERY_BUCKETS,
+        maxResponseBytes: target.query?.maxResponseBytes ?? DEFAULT_QUERY_BYTES
+      })
+    });
+    this.validateRetention(resolved, field);
+    if (resolved.leaseExpiryMs < 1e3) {
+      throw new Error(`${field}.leaseExpiry must be at least 1s`);
+    }
+    return resolved;
+  }
+  resolveLevelRetention(levels, field) {
+    if (levels === void 0) {
+      return Object.freeze({});
+    }
+    const resolved = {};
+    for (const [level, duration] of Object.entries(levels)) {
+      const normalized = level.trim().toLowerCase();
+      if (normalized.length === 0) {
+        throw new Error(`${field}.retention.levels contains an empty level name`);
+      }
+      if (resolved[normalized] !== void 0) {
+        throw new Error(`${field}.retention.levels declares "${normalized}" more than once`);
+      }
+      resolved[normalized] = this.durations.parse(
+        duration,
+        `${field}.retention.levels.${normalized}`
+      );
+    }
+    return Object.freeze(resolved);
+  }
+  validateRetention(target, field) {
+    const retention = target.retention;
+    const requiredSamplesMs = retention.rawMs + retention.lateArrivalMs;
+    if (!Number.isSafeInteger(requiredSamplesMs) || retention.samplesMs < requiredSamplesMs) {
+      throw new Error(`${field}.retention.samples must cover raw plus lateArrival`);
+    }
+    for (let index = 0; index < retention.rollups.length; index += 1) {
+      const tier = retention.rollups[index];
+      const previous = retention.rollups[index - 1];
+      if (!tier || tier.retainMs < retention.rawMs) {
+        throw new Error(`${field}.retention rollup retention cannot be shorter than raw retention`);
+      }
+      if (previous && (tier.resolutionMs <= previous.resolutionMs || tier.retainMs <= previous.retainMs)) {
+        throw new Error(
+          `${field}.retention rollup tiers must increase by resolution and retention`
+        );
+      }
+    }
+  }
+  validateTargets(role, targets, defaultTargetId) {
+    if (role === "producer") {
+      return;
+    }
+    const targetIds = targets.map((target) => target.targetId);
+    if (new Set(targetIds).size !== targetIds.length) {
+      throw new Error("Telemetry storage target ids must be unique");
+    }
+    if (!targets.some((target) => target.delivery === "required")) {
+      throw new Error("Telemetry storage requires at least one required durable target");
+    }
+    if (defaultTargetId !== null && !targetIds.includes(defaultTargetId)) {
+      throw new Error(`Unknown default telemetry target ${defaultTargetId}`);
+    }
+  }
+  resolveMetric(metric, targets, index) {
+    if (metric.selector.endsWith("[*]") && (metric.groupBy?.length ?? 0) > 0) {
+      throw new Error(`telemetry.metrics[${index}] selector [*] cannot declare groupBy`);
+    }
+    const targetIds = metric.targets ?? targets.map((target) => target.targetId);
+    if (new Set(targetIds).size !== targetIds.length) {
+      throw new Error(`telemetry.metrics[${index}] has duplicate target ids`);
+    }
+    const unknownTarget = targetIds.find(
+      (targetId) => !targets.some((target) => target.targetId === targetId)
+    );
+    if (unknownTarget !== void 0) {
+      throw new Error(`telemetry.metrics[${index}] references unknown target ${unknownTarget}`);
+    }
+    const resolutionsMs = metric.resolutions?.map(
+      (resolution, resolutionIndex) => this.durations.parse(
+        resolution,
+        `telemetry.metrics[${index}].resolutions[${resolutionIndex}]`
+      )
+    ) ?? this.metricResolutions(targets, targetIds);
+    this.validateMetricResolutions(resolutionsMs, targets, targetIds, index);
+    const cardinality = Object.freeze(
+      Object.fromEntries(
+        Object.entries(metric.cardinality ?? {}).map(([field, rule]) => [
+          field,
+          Object.freeze({ ...rule })
+        ])
+      )
+    );
+    const definition = {
+      name: metric.name,
+      version: metric.version ?? 1,
+      selector: metric.selector,
+      groupBy: Object.freeze([...metric.groupBy ?? []]),
+      measurements: Object.freeze(
+        metric.measurements.map((measurement) => this.resolveMeasurement(measurement))
+      ),
+      cardinality,
+      targetIds: Object.freeze([...targetIds]),
+      resolutionsMs: Object.freeze(resolutionsMs),
+      missingField: metric.missingField ?? "record-failure"
+    };
+    const normalized = this.metricContract.normalize(definition);
+    if (!normalized.ok) {
+      throw new Error(`telemetry.metrics[${index}]: ${normalized.error}`);
+    }
+    this.validateNormalizedMetric(normalized.value, index);
+    return normalized.value;
+  }
+  validateNormalizedMetric(definition, index) {
+    const segments = definition.selector.split(".");
+    const invalidSelector = segments.some(
+      (segment) => segment !== "*" && segment !== "**" && !/^[A-Za-z0-9_:-][A-Za-z0-9_:\-]*$/.test(segment)
+    );
+    if (invalidSelector) {
+      throw new Error(`telemetry.metrics[${index}] has an invalid dotted selector`);
+    }
+    const invalidGroupBy = definition.groupBy.find((field) => !this.isFieldPath(field));
+    if (invalidGroupBy !== void 0 || new Set(definition.groupBy).size !== definition.groupBy.length) {
+      throw new Error(`telemetry.metrics[${index}] has invalid or duplicate groupBy fields`);
+    }
+    const extraCardinality = Object.keys(definition.cardinality).find(
+      (field) => !definition.groupBy.includes(field)
+    );
+    if (extraCardinality !== void 0) {
+      throw new Error(
+        `telemetry.metrics[${index}] cardinality policy ${extraCardinality} is not a declared dimension`
+      );
+    }
+    const measurementKeys = definition.measurements.map(
+      (measurement) => measurement.kind === "count" ? "count" : `field:${measurement.field}`
+    );
+    const invalidField = definition.measurements.find(
+      (measurement) => measurement.kind === "field" && !this.isFieldPath(measurement.field)
+    );
+    if (invalidField !== void 0 || new Set(measurementKeys).size !== measurementKeys.length) {
+      throw new Error(`telemetry.metrics[${index}] has invalid or duplicate measurements`);
+    }
+  }
+  isFieldPath(value) {
+    return value.split(".").every((segment) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(segment));
+  }
+  resolveMeasurement(measurement) {
+    if (measurement === "count") {
+      return Object.freeze({ kind: "count" });
+    }
+    if (new Set(measurement.aggregate).size !== measurement.aggregate.length) {
+      throw new Error(`Metric field ${measurement.field} has duplicate aggregates`);
+    }
+    return Object.freeze({
+      kind: "field",
+      field: measurement.field,
+      aggregates: Object.freeze([...measurement.aggregate])
+    });
+  }
+  metricResolutions(targets, targetIds) {
+    const selected = targets.filter((target) => targetIds.includes(target.targetId));
+    const first = selected[0]?.retention.rollups.map((tier) => tier.resolutionMs) ?? [];
+    return first.filter(
+      (resolution) => selected.every(
+        (target) => target.retention.rollups.some((tier) => tier.resolutionMs === resolution)
+      )
+    ).sort((left, right) => left - right);
+  }
+  validateMetricResolutions(resolutions, targets, targetIds, metricIndex) {
+    for (const targetId of targetIds) {
+      const target = targets.find((candidate) => candidate.targetId === targetId);
+      const unavailable = resolutions.find(
+        (resolution) => !target?.retention.rollups.some((tier) => tier.resolutionMs === resolution)
+      );
+      if (unavailable !== void 0) {
+        throw new Error(
+          `telemetry.metrics[${metricIndex}] resolution ${unavailable} is not configured for target ${targetId}`
+        );
+      }
+    }
+  }
+  validateMetricIdentities(metrics) {
+    const identities = metrics.map((metric) => `${metric.name}:${metric.version}`);
+    if (new Set(identities).size !== identities.length) {
+      throw new Error("Metric name/version identities must be unique");
+    }
+  }
+  errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+  }
+};
+
+// src/projector/telemetry_metrics_migration.ts
+var MAX_COMBINED_DIMENSION_KEYS = 1e4;
+function metricDefinitionToTraceProjection(metric, options = {}) {
+  const measurements = [];
+  for (const measurement of metric.measurements) {
+    if (measurement.kind === "count") {
+      continue;
+    }
+    measurements.push({
+      field: measurement.field,
+      aggregates: measurement.aggregates
+    });
+  }
+  const resolutions = metric.resolutionsMs.length > 0 ? metric.resolutionsMs : options.fallbackResolutions ?? [6e4, 9e5, 36e5];
+  const dimensionPolicies = Object.entries(metric.cardinality);
+  const cardinality = dimensionPolicies.length > 0 ? {
+    // Legacy policy is per-dimension per-bucket; the projection policy is
+    // per-projection distinct dimension keys. The combined budget is the
+    // product of the per-field limits (bounded by the spec's default
+    // ceiling): `[routeKey(100), visibility(2)]` allows 200 pairs, not 2.
+    // Taking the minimum, as this did until 2026-09-03, folded the third
+    // route/visibility pair of frontend_performance_health@2 into `other`.
+    maxDimensionKeys: Math.min(
+      MAX_COMBINED_DIMENSION_KEYS,
+      dimensionPolicies.reduce((product, [, policy]) => product * policy.maxValuesPerBucket, 1)
+    ),
+    overflow: dimensionPolicies.some(([, policy]) => policy.overflow === "other") ? "other" : "reject"
+  } : void 0;
+  return {
+    name: metric.name,
+    version: metric.version,
+    event: metric.selector,
+    ...metric.groupBy.length > 0 ? { groupBy: metric.groupBy } : {},
+    measurements,
+    resolutions,
+    missingField: metric.missingField,
+    ...cardinality !== void 0 ? { cardinality } : {}
+  };
+}
+function metricDefinitionsToTraceProjections(metrics, options = {}) {
+  return metrics.map((metric) => metricDefinitionToTraceProjection(metric, options));
+}
+
+// src/projector/trace_projector_process.ts
+function createTraceProjectorProcess(options) {
+  let projections = options.projections ?? [];
+  if (options.configurationPath !== void 0) {
+    const parser = new NodeTelemetryConfigurationParser();
+    const configuration = parser.parseFile(options.configurationPath, {
+      storageBaseDirectory: import_node_path2.default.dirname(options.destinationDbPath)
+    });
+    projections = [...projections, ...metricDefinitionsToTraceProjections(configuration.metrics)];
+  }
+  if (projections.length === 0) {
+    throw new Error("TraceProjectorProcess: no projections configured");
+  }
+  const source = new import_sqlite.SqliteTraceStore({ connection: new import_better_sqlite3.default(options.tracesDbPath) });
+  (0, import_node_fs2.mkdirSync)(import_node_path2.default.dirname(options.destinationDbPath), { recursive: true });
+  const destination = new import_better_sqlite3.default(options.destinationDbPath);
+  const projector = new TraceProjector({
+    source,
+    destination,
+    projections,
+    ...options.pageSize !== void 0 ? { pageSize: options.pageSize } : {}
+  });
+  return {
+    projector,
+    runOnce: () => projector.runOnce(),
+    close: () => {
+      source.close();
+      destination.close();
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  TraceProjector,
+  createTraceProjectorProcess,
+  detectSourceReset,
+  eventSelectorMatches,
+  metricDefinitionToTraceProjection,
+  metricDefinitionsToTraceProjections,
+  validateTraceProjection
+});
+//# sourceMappingURL=index.cjs.map