@oqtopus-team/pi-qdash 0.1.4 → 0.1.6

package/extensions/lib/timeseries-analysis.ts

@@ -0,0 +1,609 @@
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+export type NumericTimeseriesPoint = { at: string | number | Date; value: number };
+export type NumericTimeseries = {
+  label: string;
+  unit?: string;
+  source: "qdash" | "csv";
+  points: NumericTimeseriesPoint[];
+};
+
+export type CsvTimeFormat =
+  | "iso"
+  | "yyyy/M/d H:mm"
+  | "yyyy-MM-dd HH:mm:ss"
+  | "unix-seconds"
+  | "unix-milliseconds";
+
+export type CsvValueColumn = {
+  column: string;
+  label?: string;
+  unit?: string;
+  scale?: number;
+  offset?: number;
+};
+
+export type ExternalCsvSpec = {
+  path: string;
+  timeColumn: string;
+  valueColumns: CsvValueColumn[];
+  timeFormat?: CsvTimeFormat;
+  timezoneOffsetMinutes?: number;
+  delimiter?: string;
+  skipRows?: number;
+  filters?: Record<string, string[]>;
+};
+
+export type CsvInspection = {
+  path: string;
+  headers: string[];
+  dataRows: number;
+  scannedRows: number;
+  columns: Array<{
+    column: string;
+    nonEmpty: number;
+    numeric: number;
+    numericFraction: number;
+    min?: number;
+    max?: number;
+    samples: string[];
+  }>;
+  time?: {
+    column: string;
+    valid: number;
+    invalid: number;
+    firstAt?: string;
+    lastAt?: string;
+    medianCadenceMinutes?: number;
+  };
+};
+
+export type TimeseriesTransformOptions = {
+  startAt?: string;
+  endAt?: string;
+  resampleMinutes?: number;
+  smoothingWindowMinutes?: number;
+  detrend?: "none" | "linear";
+  normalize?: "none" | "zscore";
+  maxInterpolationGapMinutes?: number;
+  periodSearch?: { minMinutes: number; maxMinutes: number; stepMinutes?: number };
+  includeAlignedData?: boolean;
+};
+
+export type SeriesStatistics = {
+  label: string;
+  source: "qdash" | "csv";
+  unit?: string;
+  inputPoints: number;
+  firstAt: string;
+  lastAt: string;
+  min: number;
+  max: number;
+  mean: number;
+  standardDeviation: number;
+};
+
+export type PairwiseComparison = {
+  left: string;
+  right: string;
+  correlation: number | null;
+  phaseDifferenceDegrees?: number;
+};
+
+export type PeriodicFit = {
+  label: string;
+  periodMinutes: number;
+  phaseDegrees: number;
+  periodicExplainedFraction: number;
+};
+
+export type TimeseriesComparison = {
+  overlap: {
+    startAt: string;
+    endAt: string;
+    durationMinutes: number;
+    alignedPoints: number;
+    resampleMinutes: number;
+    observedCycles?: number;
+  };
+  transforms: {
+    smoothingWindowMinutes: number;
+    detrend: "none" | "linear";
+    normalize: "none" | "zscore";
+    maxInterpolationGapMinutes: number;
+  };
+  series: SeriesStatistics[];
+  pairs: PairwiseComparison[];
+  periodicFits?: PeriodicFit[];
+  warnings: string[];
+  alignedData?: Array<{ at: string; values: Record<string, number> }>;
+};
+
+const MAX_CSV_BYTES = 10 * 1024 * 1024;
+const MAX_GRID_POINTS = 100_000;
+
+function parseCsv(text: string, delimiter: string): string[][] {
+  if (delimiter.length !== 1) throw new Error("CSV delimiter must be exactly one character");
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let quoted = false;
+  for (let index = 0; index < text.length; index++) {
+    const character = text[index];
+    if (quoted) {
+      if (character === '"' && text[index + 1] === '"') {
+        field += '"';
+        index++;
+      } else if (character === '"') quoted = false;
+      else field += character;
+      continue;
+    }
+    if (character === '"') quoted = true;
+    else if (character === delimiter) {
+      row.push(field);
+      field = "";
+    } else if (character === "\n") {
+      row.push(field.replace(/\r$/, ""));
+      rows.push(row);
+      row = [];
+      field = "";
+    } else field += character;
+  }
+  if (quoted) throw new Error("CSV contains an unterminated quoted field");
+  if (field.length > 0 || row.length > 0) {
+    row.push(field.replace(/\r$/, ""));
+    rows.push(row);
+  }
+  return rows;
+}
+
+function timestampFromParts(parts: number[], timezoneOffsetMinutes: number): number {
+  const [year, month, day, hour = 0, minute = 0, second = 0] = parts;
+  return Date.UTC(year, month - 1, day, hour, minute, second) - timezoneOffsetMinutes * 60_000;
+}
+
+function parseCsvTimestamp(value: string, format: CsvTimeFormat, timezoneOffsetMinutes?: number): number {
+  const trimmed = value.trim();
+  if (format === "unix-seconds" || format === "unix-milliseconds") {
+    const numeric = Number(trimmed);
+    if (!Number.isFinite(numeric)) throw new Error(`Invalid ${format} timestamp: ${value}`);
+    return format === "unix-seconds" ? numeric * 1000 : numeric;
+  }
+  if (format === "iso") {
+    const hasZone = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(trimmed);
+    if (!hasZone && timezoneOffsetMinutes === undefined) {
+      throw new Error("Naive ISO timestamps require timezoneOffsetMinutes");
+    }
+    const zoned = hasZone
+      ? trimmed
+      : `${trimmed}${formatOffset(timezoneOffsetMinutes ?? 0)}`;
+    const parsed = Date.parse(zoned);
+    if (!Number.isFinite(parsed)) throw new Error(`Invalid ISO timestamp: ${value}`);
+    return parsed;
+  }
+  if (timezoneOffsetMinutes === undefined) {
+    throw new Error(`${format} timestamps require timezoneOffsetMinutes`);
+  }
+  const expression = format === "yyyy/M/d H:mm"
+    ? /^(\d{4})\/(\d{1,2})\/(\d{1,2})\s+(\d{1,2}):(\d{2})$/
+    : /^(\d{4})-(\d{1,2})-(\d{1,2})\s+(\d{1,2}):(\d{2}):(\d{2})$/;
+  const match = trimmed.match(expression);
+  if (!match) throw new Error(`Timestamp does not match ${format}: ${value}`);
+  return timestampFromParts(match.slice(1).map(Number), timezoneOffsetMinutes);
+}
+
+function formatOffset(minutes: number): string {
+  const sign = minutes >= 0 ? "+" : "-";
+  const absolute = Math.abs(minutes);
+  return `${sign}${String(Math.floor(absolute / 60)).padStart(2, "0")}:${String(absolute % 60).padStart(2, "0")}`;
+}
+
+function csvRows(pathInput: string, cwd: string, delimiter = ",", skipRows = 0): { path: string; rows: string[][]; headers: string[] } {
+  const rawPath = pathInput.startsWith("@") ? pathInput.slice(1) : pathInput;
+  const path = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
+  const size = statSync(path).size;
+  if (size > MAX_CSV_BYTES) throw new Error(`CSV exceeds 10 MB limit: ${path}`);
+  if (!Number.isInteger(skipRows) || skipRows < 0) throw new Error("skipRows must be a non-negative integer");
+  const rows = parseCsv(readFileSync(path, "utf8"), delimiter).slice(skipRows);
+  if (rows.length < 2) throw new Error(`CSV has no data rows: ${path}`);
+  return { path, rows, headers: rows[0].map((header) => header.trim().replace(/^\uFEFF/, "")) };
+}
+
+function findHeader(headers: string[], requested: string): number {
+  const exact = headers.indexOf(requested);
+  if (exact >= 0) return exact;
+  const normalized = requested.trim().replace(/^#/, "");
+  return headers.findIndex((header) => header.replace(/^#/, "") === normalized);
+}
+
+export function inspectExternalCsv(spec: {
+  path: string;
+  delimiter?: string;
+  skipRows?: number;
+  timeColumn?: string;
+  timeFormat?: CsvTimeFormat;
+  timezoneOffsetMinutes?: number;
+  scanRows?: number;
+}, cwd: string): CsvInspection {
+  const { path, rows, headers } = csvRows(spec.path, cwd, spec.delimiter, spec.skipRows);
+  const scanLimit = spec.scanRows ?? 10_000;
+  if (!Number.isInteger(scanLimit) || scanLimit < 1 || scanLimit > 100_000) throw new Error("scanRows must be an integer from 1 to 100000");
+  const data = rows.slice(1, scanLimit + 1).filter((row) => !row.every((field) => field.trim() === ""));
+  const columns = headers.map((column, index) => {
+    const values = data.map((row) => (row[index] ?? "").trim()).filter(Boolean);
+    const numericValues = values.map(Number).filter(Number.isFinite);
+    return {
+      column,
+      nonEmpty: values.length,
+      numeric: numericValues.length,
+      numericFraction: values.length === 0 ? 0 : numericValues.length / values.length,
+      min: numericValues.length === 0 ? undefined : Math.min(...numericValues),
+      max: numericValues.length === 0 ? undefined : Math.max(...numericValues),
+      samples: [...new Set(values)].slice(0, 3),
+    };
+  });
+  const inspection: CsvInspection = { path, headers, dataRows: rows.length - 1, scannedRows: data.length, columns };
+  if (spec.timeColumn) {
+    const index = findHeader(headers, spec.timeColumn);
+    if (index < 0) throw new Error(`CSV time column not found: ${spec.timeColumn}`);
+    const format = spec.timeFormat ?? "iso";
+    const timestamps: number[] = [];
+    let invalid = 0;
+    for (const row of data) {
+      try {
+        timestamps.push(parseCsvTimestamp(row[index] ?? "", format, spec.timezoneOffsetMinutes));
+      } catch {
+        invalid++;
+      }
+    }
+    timestamps.sort((a, b) => a - b);
+    const intervals = timestamps.slice(1).map((value, item) => (value - timestamps[item]) / 60_000).filter((value) => value > 0).sort((a, b) => a - b);
+    inspection.time = {
+      column: headers[index],
+      valid: timestamps.length,
+      invalid,
+      firstAt: timestamps.length ? new Date(timestamps[0]).toISOString() : undefined,
+      lastAt: timestamps.length ? new Date(timestamps.at(-1)!).toISOString() : undefined,
+      medianCadenceMinutes: intervals.length ? intervals[Math.floor(intervals.length / 2)] : undefined,
+    };
+  }
+  return inspection;
+}
+
+export function csvInspectionText(inspection: CsvInspection): string {
+  const lines = [
+    `CSV ${inspection.path}`,
+    `rows ${inspection.dataRows} (scanned ${inspection.scannedRows})`,
+    `headers ${inspection.headers.join(", ")}`,
+    "",
+    "Columns",
+    ...inspection.columns.map((column) => `- ${column.column}: non-empty=${column.nonEmpty}, numeric=${column.numeric} (${(column.numericFraction * 100).toFixed(1)}%)${column.min === undefined ? "" : `, range=${column.min}..${column.max}`}, samples=${column.samples.map((sample) => JSON.stringify(sample)).join(", ")}`),
+  ];
+  if (inspection.time) lines.push("", `Time ${inspection.time.column}: valid=${inspection.time.valid}, invalid=${inspection.time.invalid}, range=${inspection.time.firstAt ?? "n/a"}..${inspection.time.lastAt ?? "n/a"}, median cadence=${inspection.time.medianCadenceMinutes ?? "n/a"} min`);
+  return lines.join("\n");
+}
+
+export function loadExternalCsvSeries(spec: ExternalCsvSpec, cwd: string): NumericTimeseries[] {
+  const { rows, headers } = csvRows(spec.path, cwd, spec.delimiter, spec.skipRows);
+  const timeFormat = spec.timeFormat ?? "iso";
+  const supportedFormats: CsvTimeFormat[] = ["iso", "yyyy/M/d H:mm", "yyyy-MM-dd HH:mm:ss", "unix-seconds", "unix-milliseconds"];
+  if (!supportedFormats.includes(timeFormat)) throw new Error(`Unsupported CSV timeFormat: ${String(timeFormat)}`);
+  const findHeaderIndex = (requested: string) => findHeader(headers, requested);
+  const timeIndex = findHeaderIndex(spec.timeColumn);
+  if (timeIndex < 0) throw new Error(`CSV time column not found: ${spec.timeColumn}`);
+  const columns = spec.valueColumns.map((column) => {
+    const index = findHeaderIndex(column.column);
+    if (index < 0) throw new Error(`CSV value column not found: ${column.column}`);
+    return { ...column, index };
+  });
+  const filters = Object.entries(spec.filters ?? {}).map(([column, accepted]) => {
+    const index = findHeaderIndex(column);
+    if (index < 0) throw new Error(`CSV filter column not found: ${column}`);
+    if (accepted.length === 0) throw new Error(`CSV filter ${column} must contain at least one accepted value`);
+    return { index, accepted: new Set(accepted) };
+  });
+  const output = columns.map((column) => ({
+    label: column.label ?? column.column,
+    unit: column.unit,
+    source: "csv" as const,
+    points: [] as NumericTimeseriesPoint[],
+  }));
+  for (let rowIndex = 1; rowIndex < rows.length; rowIndex++) {
+    const row = rows[rowIndex];
+    if (row.every((field) => field.trim() === "")) continue;
+    if (filters.some((filter) => !filter.accepted.has((row[filter.index] ?? "").trim()))) continue;
+    let at: number;
+    try {
+      at = parseCsvTimestamp(row[timeIndex] ?? "", timeFormat, spec.timezoneOffsetMinutes);
+    } catch (error) {
+      throw new Error(`CSV row ${rowIndex + 1}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    columns.forEach((column, columnIndex) => {
+      const value = Number((row[column.index] ?? "").trim());
+      if (!Number.isFinite(value)) return;
+      output[columnIndex].points.push({
+        at,
+        value: value * (column.scale ?? 1) + (column.offset ?? 0),
+      });
+    });
+  }
+  return output;
+}
+
+function epoch(value: string | number | Date): number {
+  const parsed = typeof value === "number" ? value : value instanceof Date ? value.getTime() : Date.parse(value);
+  if (!Number.isFinite(parsed)) throw new Error(`Invalid timeseries timestamp: ${String(value)}`);
+  return parsed;
+}
+
+function preparedPoints(series: NumericTimeseries, start?: number, end?: number): Array<{ at: number; value: number }> {
+  const byTime = new Map<number, number>();
+  for (const point of series.points) {
+    if (!Number.isFinite(point.value)) continue;
+    const at = epoch(point.at);
+    if ((start !== undefined && at < start) || (end !== undefined && at > end)) continue;
+    byTime.set(at, point.value);
+  }
+  return [...byTime.entries()].map(([at, value]) => ({ at, value })).sort((a, b) => a.at - b.at);
+}
+
+function interpolate(points: Array<{ at: number; value: number }>, at: number, maxGapMs: number): number | undefined {
+  let low = 0;
+  let high = points.length - 1;
+  while (low <= high) {
+    const middle = Math.floor((low + high) / 2);
+    if (points[middle].at < at) low = middle + 1;
+    else if (points[middle].at > at) high = middle - 1;
+    else return points[middle].value;
+  }
+  const right = points[low];
+  const left = points[low - 1];
+  if (!left || !right || right.at - left.at > maxGapMs) return undefined;
+  return left.value + (right.value - left.value) * ((at - left.at) / (right.at - left.at));
+}
+
+function centeredMean(values: number[], width: number): number[] {
+  if (width <= 1) return [...values];
+  const before = Math.floor(width / 2);
+  const after = width - before - 1;
+  return values.map((_value, index) => {
+    const slice = values.slice(Math.max(0, index - before), Math.min(values.length, index + after + 1));
+    return slice.reduce((sum, value) => sum + value, 0) / slice.length;
+  });
+}
+
+function linearDetrend(values: number[]): number[] {
+  const count = values.length;
+  const meanX = (count - 1) / 2;
+  const meanY = values.reduce((sum, value) => sum + value, 0) / count;
+  let numerator = 0;
+  let denominator = 0;
+  values.forEach((value, index) => {
+    numerator += (index - meanX) * (value - meanY);
+    denominator += (index - meanX) ** 2;
+  });
+  const slope = denominator === 0 ? 0 : numerator / denominator;
+  return values.map((value, index) => value - (meanY + slope * (index - meanX)));
+}
+
+function zscore(values: number[]): number[] {
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  const variance = values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / Math.max(1, values.length - 1);
+  const deviation = Math.sqrt(variance);
+  return deviation === 0 ? values.map(() => 0) : values.map((value) => (value - mean) / deviation);
+}
+
+function pearson(left: number[], right: number[]): number | null {
+  if (left.length < 3 || right.length !== left.length) return null;
+  const leftMean = left.reduce((sum, value) => sum + value, 0) / left.length;
+  const rightMean = right.reduce((sum, value) => sum + value, 0) / right.length;
+  let numerator = 0;
+  let leftSquare = 0;
+  let rightSquare = 0;
+  left.forEach((value, index) => {
+    const a = value - leftMean;
+    const b = right[index] - rightMean;
+    numerator += a * b;
+    leftSquare += a * a;
+    rightSquare += b * b;
+  });
+  const denominator = Math.sqrt(leftSquare * rightSquare);
+  return denominator === 0 ? null : numerator / denominator;
+}
+
+function solve(matrix: number[][], vector: number[]): number[] | undefined {
+  const augmented = matrix.map((row, index) => [...row, vector[index]]);
+  for (let column = 0; column < matrix.length; column++) {
+    let pivot = column;
+    for (let row = column + 1; row < matrix.length; row++) {
+      if (Math.abs(augmented[row][column]) > Math.abs(augmented[pivot][column])) pivot = row;
+    }
+    if (Math.abs(augmented[pivot][column]) < 1e-12) return undefined;
+    [augmented[column], augmented[pivot]] = [augmented[pivot], augmented[column]];
+    const divisor = augmented[column][column];
+    for (let index = column; index <= matrix.length; index++) augmented[column][index] /= divisor;
+    for (let row = 0; row < matrix.length; row++) {
+      if (row === column) continue;
+      const factor = augmented[row][column];
+      for (let index = column; index <= matrix.length; index++) augmented[row][index] -= factor * augmented[column][index];
+    }
+  }
+  return augmented.map((row) => row[matrix.length]);
+}
+
+function sinusoidFit(values: number[], periodSamples: number): { explained: number; phase: number } | undefined {
+  const rows = values.map((_value, index) => [1, index, Math.sin(2 * Math.PI * index / periodSamples), Math.cos(2 * Math.PI * index / periodSamples)]);
+  const normal = Array.from({ length: 4 }, (_unused, row) => Array.from({ length: 4 }, (_unused2, column) => rows.reduce((sum, item) => sum + item[row] * item[column], 0)));
+  const target = Array.from({ length: 4 }, (_unused, column) => rows.reduce((sum, item, index) => sum + item[column] * values[index], 0));
+  const coefficients = solve(normal, target);
+  if (!coefficients) return undefined;
+  const baseline = linearDetrend(values);
+  const residual = values.map((value, index) => value - rows[index].reduce((sum, item, column) => sum + item * coefficients[column], 0));
+  const baselineSquares = baseline.reduce((sum, value) => sum + value ** 2, 0);
+  const residualSquares = residual.reduce((sum, value) => sum + value ** 2, 0);
+  return {
+    explained: baselineSquares === 0 ? 0 : Math.max(0, Math.min(1, 1 - residualSquares / baselineSquares)),
+    phase: Math.atan2(coefficients[3], coefficients[2]),
+  };
+}
+
+function descriptive(series: NumericTimeseries, points: Array<{ at: number; value: number }>): SeriesStatistics {
+  const values = points.map((point) => point.value);
+  const mean = values.reduce((sum, value) => sum + value, 0) / values.length;
+  return {
+    label: series.label,
+    source: series.source,
+    unit: series.unit,
+    inputPoints: values.length,
+    firstAt: new Date(points[0].at).toISOString(),
+    lastAt: new Date(points.at(-1)!.at).toISOString(),
+    min: Math.min(...values),
+    max: Math.max(...values),
+    mean,
+    standardDeviation: Math.sqrt(values.reduce((sum, value) => sum + (value - mean) ** 2, 0) / Math.max(1, values.length - 1)),
+  };
+}
+
+export function compareTimeseries(inputSeries: NumericTimeseries[], options: TimeseriesTransformOptions = {}): TimeseriesComparison {
+  if (inputSeries.length < 2) throw new Error("At least two timeseries are required");
+  const labels = inputSeries.map((series) => series.label);
+  if (new Set(labels).size !== labels.length) throw new Error("Timeseries labels must be unique");
+  const requestedStart = options.startAt ? epoch(options.startAt) : undefined;
+  const requestedEnd = options.endAt ? epoch(options.endAt) : undefined;
+  const prepared = inputSeries.map((series) => preparedPoints(series, requestedStart, requestedEnd));
+  prepared.forEach((points, index) => {
+    if (points.length < 2) throw new Error(`Timeseries ${inputSeries[index].label} has fewer than two usable points`);
+  });
+  const start = Math.max(...prepared.map((points) => points[0].at));
+  const end = Math.min(...prepared.map((points) => points.at(-1)!.at));
+  if (start >= end) throw new Error("Timeseries have no overlapping time range");
+  const stepMinutes = options.resampleMinutes ?? 1;
+  if (!(stepMinutes > 0)) throw new Error("resampleMinutes must be greater than zero");
+  const stepMs = stepMinutes * 60_000;
+  const sourceCadences = prepared.map((points) => {
+    const intervals = points.slice(1).map((point, index) => (point.at - points[index].at) / 60_000).filter((value) => value > 0).sort((a, b) => a - b);
+    return intervals.length === 0 ? stepMinutes : intervals[Math.floor(intervals.length / 2)];
+  });
+  const maxGapMinutes = options.maxInterpolationGapMinutes ?? Math.max(stepMinutes * 5, ...sourceCadences.map((cadence) => cadence * 3));
+  if (!(maxGapMinutes > 0)) throw new Error("maxInterpolationGapMinutes must be greater than zero");
+  const gridCount = Math.floor((end - start) / stepMs) + 1;
+  if (gridCount > MAX_GRID_POINTS) throw new Error(`Aligned grid exceeds ${MAX_GRID_POINTS} points; increase resampleMinutes or shorten the range`);
+  const alignedAt: number[] = [];
+  const rawAligned = inputSeries.map(() => [] as number[]);
+  for (let at = start; at <= end; at += stepMs) {
+    const values = prepared.map((points) => interpolate(points, at, maxGapMinutes * 60_000));
+    if (values.some((value) => value === undefined)) continue;
+    alignedAt.push(at);
+    values.forEach((value, index) => rawAligned[index].push(value!));
+  }
+  if (alignedAt.length < 3) throw new Error("Fewer than three aligned points remain after interpolation gap filtering");
+  const smoothingMinutes = options.smoothingWindowMinutes ?? 0;
+  if (smoothingMinutes < 0) throw new Error("smoothingWindowMinutes must not be negative");
+  const smoothingWidth = Math.max(1, Math.round(smoothingMinutes / stepMinutes));
+  const transformed = rawAligned.map((values) => {
+    let output = centeredMean(values, smoothingWidth);
+    if ((options.detrend ?? "none") === "linear") output = linearDetrend(output);
+    if ((options.normalize ?? "none") === "zscore") output = zscore(output);
+    return output;
+  });
+  const pairs: PairwiseComparison[] = [];
+  for (let left = 0; left < inputSeries.length; left++) {
+    for (let right = left + 1; right < inputSeries.length; right++) {
+      pairs.push({ left: labels[left], right: labels[right], correlation: pearson(transformed[left], transformed[right]) });
+    }
+  }
+  let periodicFits: PeriodicFit[] | undefined;
+  let observedCycles: number | undefined;
+  const warnings: string[] = [];
+  if (options.periodSearch) {
+    const { minMinutes, maxMinutes, stepMinutes: searchStep = Math.max(0.1, stepMinutes / 10) } = options.periodSearch;
+    if (!(minMinutes > 0 && maxMinutes > minMinutes && searchStep > 0)) throw new Error("periodSearch must have 0 < minMinutes < maxMinutes and a positive stepMinutes");
+    let bestPeriod = minMinutes;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    for (let period = minMinutes; period <= maxMinutes + searchStep / 2; period += searchStep) {
+      const fits = transformed.map((values) => sinusoidFit(values, period / stepMinutes));
+      const score = fits.reduce((sum, fit) => sum + (fit?.explained ?? 0), 0);
+      if (score > bestScore) {
+        bestScore = score;
+        bestPeriod = period;
+      }
+    }
+    periodicFits = transformed.map((values, index) => {
+      const fit = sinusoidFit(values, bestPeriod / stepMinutes)!;
+      return {
+        label: labels[index],
+        periodMinutes: bestPeriod,
+        phaseDegrees: ((fit.phase * 180 / Math.PI) % 360 + 360) % 360,
+        periodicExplainedFraction: fit.explained,
+      };
+    });
+    for (const pair of pairs) {
+      const left = periodicFits.find((fit) => fit.label === pair.left)!;
+      const right = periodicFits.find((fit) => fit.label === pair.right)!;
+      let difference = left.phaseDegrees - right.phaseDegrees;
+      while (difference > 180) difference -= 360;
+      while (difference <= -180) difference += 360;
+      pair.phaseDifferenceDegrees = difference;
+    }
+    observedCycles = ((alignedAt.at(-1)! - alignedAt[0]) / 60_000) / bestPeriod;
+    if (observedCycles < 5) warnings.push(`Only ${observedCycles.toFixed(1)} cycles of the selected period are observed; periodic inference is preliminary.`);
+  }
+  warnings.push("Correlation and shared periodicity do not by themselves establish a causal direction or exclude a common driver.");
+  if (smoothingMinutes > 0) warnings.push("Smoothing and interpolation introduce autocorrelation; aligned points are not independent observations.");
+  const result: TimeseriesComparison = {
+    overlap: {
+      startAt: new Date(alignedAt[0]).toISOString(),
+      endAt: new Date(alignedAt.at(-1)!).toISOString(),
+      durationMinutes: (alignedAt.at(-1)! - alignedAt[0]) / 60_000,
+      alignedPoints: alignedAt.length,
+      resampleMinutes: stepMinutes,
+      observedCycles,
+    },
+    transforms: {
+      smoothingWindowMinutes: smoothingMinutes,
+      detrend: options.detrend ?? "none",
+      normalize: options.normalize ?? "none",
+      maxInterpolationGapMinutes: maxGapMinutes,
+    },
+    series: inputSeries.map((series, index) => descriptive(series, prepared[index])),
+    pairs,
+    periodicFits,
+    warnings,
+  };
+  if (options.includeAlignedData) {
+    if (alignedAt.length > 5_000) throw new Error("includeAlignedData is limited to 5,000 aligned rows; shorten the range or increase resampleMinutes");
+    result.alignedData = alignedAt.map((at, row) => ({
+      at: new Date(at).toISOString(),
+      values: Object.fromEntries(labels.map((label, column) => [label, transformed[column][row]])),
+    }));
+  }
+  return result;
+}
+
+function number(value: number | null | undefined, digits = 3): string {
+  return value === null || value === undefined || !Number.isFinite(value) ? "n/a" : value.toFixed(digits);
+}
+
+export function timeseriesComparisonText(comparison: TimeseriesComparison): string {
+  const lines = [
+    "Timeseries comparison",
+    `overlap ${comparison.overlap.startAt} → ${comparison.overlap.endAt}`,
+    `aligned ${comparison.overlap.alignedPoints} points every ${comparison.overlap.resampleMinutes} min`,
+    `transform smooth=${comparison.transforms.smoothingWindowMinutes} min detrend=${comparison.transforms.detrend} normalize=${comparison.transforms.normalize}`,
+    "",
+    "Series",
+    ...comparison.series.map((series) => `- ${series.label} (${series.source}): n=${series.inputPoints}, min=${number(series.min)}${series.unit ? ` ${series.unit}` : ""}, max=${number(series.max)}${series.unit ? ` ${series.unit}` : ""}`),
+    "",
+    "Pairwise correlation",
+    ...comparison.pairs.map((pair) => `- ${pair.left} vs ${pair.right}: r=${number(pair.correlation)}${pair.phaseDifferenceDegrees === undefined ? "" : `, phase=${number(pair.phaseDifferenceDegrees, 1)}°`}`),
+  ];
+  if (comparison.periodicFits) {
+    lines.push("", "Shared-period fit");
+    for (const fit of comparison.periodicFits) {
+      lines.push(`- ${fit.label}: period=${number(fit.periodMinutes, 1)} min, phase=${number(fit.phaseDegrees, 1)}°, explained=${number(fit.periodicExplainedFraction * 100, 1)}%`);
+    }
+  }
+  lines.push("", "Warnings", ...comparison.warnings.map((warning) => `- ${warning}`));
+  return lines.join("\n");
+}

package/extensions/lib/write-gate.ts

@@ -10,6 +10,7 @@ const WRITE_TOOL_NAMES = new Set([
   "qdash_create_forum_post",
   "qdash_update_forum_post",
   "qdash_create_forum_evidence_reply",
+  "qdash_create_forum_image_reply",
 ]);
 
 export function installQDashWriteGate(pi: ExtensionAPI): void {