ephemeris-cli 0.0.0-stage → 0.4.0

package/src/describe.js

@@ -0,0 +1,87 @@
+import { selectForecast } from './artifact.js';
+
+export const limitations = [
+  'Forecasting alone does not establish accuracy or calibrated uncertainty.',
+  'Quantile bands are marginal predictive quantiles, not verified coverage or confidence intervals for model accuracy.',
+  'Marginal quantiles cannot establish cumulative-total intervals or path-dependent probabilities.',
+  'The highest marginal median is not the distribution of the actual peak.',
+  'Observed sales are not necessarily underlying demand. Zeros do not establish stockouts or lost demand.',
+  'No causal explanation, trading action, inventory action, or business recommendation is inferred.',
+  'Known-future labels and scenario assumptions are caller assertions; availability has not been independently verified.',
+  'Absent future covariates or an empty assumptions list means not supplied, not an assumption of zero events, no promotions, no constraints, or unchanged conditions.',
+  'A jump from the last observation or a narrow/constant quantile band alone does not establish forecast quality, poor fit, accuracy, or calibration; observed outcomes and evaluation are needed.',
+];
+
+const finite = (v) => Number.isFinite(v) ? v : null;
+export function billingSummary(billing) {
+  const amount = (name) => typeof billing?.[name] === 'string' && /^-?\d+$/.test(billing[name]) ? billing[name] : null;
+  const credits = (mc) => {
+    if (mc === null) return null;
+    const negative = mc.startsWith('-'), digits = (negative ? mc.slice(1) : mc).replace(/^0+(?=\d)/, '').padStart(4, '0');
+    const fraction = digits.slice(-3).replace(/0+$/, '');
+    return `${negative && /[1-9]/.test(digits) ? '-' : ''}${digits.slice(0,-3)}${fraction ? `.${fraction}` : ''}`;
+  };
+  const settled = amount('settled_mc'), balance = amount('balance_mc');
+  return { scope: 'saved response; not a current balance check', unit: 'millicredits', conversion: '1000 millicredits = 1 credit; amounts remain exact decimal strings', settled_mc: settled, settled_credits: credits(settled), balance_mc: balance, balance_credits: credits(balance), source_pointer: '/response/meta/billing' };
+}
+export function mean(values) {
+  if (!values.length || values.some((v) => v === null)) return null;
+  // Compensated accumulation of scaled terms avoids avoidable sum overflow.
+  let sum = 0, correction = 0;
+  for (const v of values) { const x = v / values.length - correction; const next = sum + x; correction = (next - sum) - x; sum = next; }
+  return finite(sum);
+}
+export function observedStatistics(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  return { count: values.length, latest: values.at(-1), minimum: sorted[0], maximum: sorted.at(-1), mean: mean(values), median: sorted.length % 2 ? sorted[(sorted.length - 1) / 2] : mean(sorted.slice(sorted.length / 2 - 1, sorted.length / 2 + 1)) };
+}
+
+export function describe(value, options) {
+  const selected = selectForecast(value, options);
+  const { artifact: a, i, j, history, context, quantiles, pointer, history_pointer } = selected;
+  const median = quantiles['0.5'] ?? null;
+  const medianKey = Object.keys(a.response.forecasts[i].quantiles).find((q) => Number(q) === 0.5);
+  const last = history.at(-1);
+  const end = median?.at(-1) ?? null;
+  const complete = median !== null && median.every((v) => v !== null);
+  const maximum = complete ? Math.max(...median) : null;
+  const medianMean = complete ? mean(median) : null;
+  const notes = [...limitations];
+  if (!median) notes.push('No median was returned. It is not interpolated from other quantiles.');
+  else if (!complete) notes.push('Median contains missing values. Horizon-wide aggregates and maxima are not calculated.');
+  if (context.unit === null) notes.push('Unit is unknown. No unit conversion or financial interpretation is performed.');
+  if (context.measurement === null) notes.push('Measurement semantics are unknown; no period total is calculated.');
+  if (context.future_axis.kind === 'steps') notes.push(context.future_axis.reason);
+  const levels = Object.keys(quantiles).map(Number).sort((a, b) => a - b);
+  const crossing = Array.from({ length: a.request.horizon ?? 64 }, (_, index) => {
+    const observed = levels.map((q) => quantiles[q][index]).filter((v) => v !== null);
+    return observed.some((v, k) => k > 0 && v < observed[k - 1]);
+  }).filter(Boolean).length;
+  if (crossing) notes.push('Returned quantiles cross at some steps. Values are preserved; crossed bands must not be interpreted as ordered intervals.');
+  return { schema_version: '1', operation: 'forecast_describe', status: { operation: 'ok', scoring: 'not_performed', evidence_complete: null },
+    scope: { series_index: i, variate_index: j, series_id: context.series_id, unit: context.unit, variable: context.target_description, measurement: context.measurement, timezone: context.timezone, frequency: a.request.series[i].freq ?? null, horizon: a.request.horizon ?? 64, horizon_unit: 'sampling_steps', axis: context.future_axis },
+    result: {
+      billing: billingSummary(a.response.meta?.billing),
+      point_definition: 'marginal_median', point_pointer: median ? `${pointer}/${medianKey}${Array.isArray(a.request.series[i].values[0]) ? `/${j}` : ''}` : null,
+      ...(median && median.length <= 8 ? { point: median } : {}), quantiles_pointer: pointer,
+      observed: { ...observedStatistics(history), source_pointer: history_pointer, scope: 'full submitted history; service may truncate context' },
+      median_missing_count: median ? median.filter((v) => v === null).length : null,
+      final_median: end,
+      change_from_last_observed: end === null ? null : finite(end - last),
+      percent_change_from_last_observed: end === null || last === 0 ? null : finite(((end - last) / Math.abs(last)) * 100),
+      mean_of_marginal_medians: medianMean,
+      sum_of_marginal_medians: medianMean !== null && context.measurement === 'period_total' ? finite(medianMean * median.length) : null,
+      sum_interpretation: context.measurement === 'period_total' ? 'Arithmetic sum of per-step medians, not the median or interval of the cumulative distribution.' : 'Not calculated: measurement is not declared period_total.',
+      highest_marginal_median: maximum === null ? null : { value: maximum, steps: median.flatMap((v, k) => v === maximum ? [k + 1] : []) },
+      quantile_crossing_steps: crossing,
+    },
+    basis: { kind: 'deterministic_saved_result', baseline: { name: 'last_observed_value', value: last, pointer: `${history_pointer}/${history.length - 1}` }, methods: {
+      observed_mean: 'Compensated arithmetic mean of all submitted observations.', observed_median: 'Middle sorted observation, or arithmetic mean of the two middle observations.',
+      change: 'Final marginal median minus last observed value.', percent_change: '100 * (final marginal median - last observation) / abs(last observation); null for a zero baseline.',
+      aggregates: 'Arithmetic calculations on marginal medians only; null for missing inputs or non-finite arithmetic.', peak: 'Maximum marginal median with all tied one-based steps; not a peak-outcome distribution.',
+    }, provider_calls: 0, local_context_pointer: '/context', models_used_pointer: '/response/meta/models_used' },
+    limitations: notes,
+    references: { artifact_id: a.artifact_id, request_fingerprint: a.request_sha256, snapshot_id: a.context.snapshot_id, gateway_request_id: a.response.meta?.gateway_request_id ?? a.transport?.request_id ?? null, provider_request_id: a.response.meta?.request_id ?? null, billing_pointer: '/response/meta/billing', pointer_root: 'input forecast artifact', recorded: false },
+    followups: [],
+  };
+}

package/src/errors.js

@@ -0,0 +1,14 @@
+export class CliError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function redact(value, key) {
+  // Sanitize even upstream errors that echo a bearer token.
+  let text = String(value);
+  if (key) text = text.split(key).join('[REDACTED]');
+  return text.replace(/pc_live_[A-Za-z0-9_-]+/g, '[REDACTED]');
+}

package/src/io.js

@@ -0,0 +1,74 @@
+import { open, readFile, unlink } from 'node:fs/promises';
+import { CliError, redact } from './errors.js';
+
+export async function readText(file) {
+  if (!file) throw new CliError(2, '--input is required. Use a file or - for stdin.');
+  try {
+    let buffer;
+    if (file === '-') {
+      if (process.stdin.isTTY) throw new CliError(2, 'Pipe input to stdin or provide a file.');
+      const chunks = []; let length = 0;
+      for await (const chunk of process.stdin) {
+        length += chunk.length;
+        if (length > 8 * 1024 * 1024) throw new CliError(2, 'Input exceeds the 8 MiB limit. Partition it explicitly.');
+        chunks.push(chunk);
+      }
+      buffer = Buffer.concat(chunks);
+    } else {
+      const handle = await open(file, 'r');
+      try {
+        const stats = await handle.stat();
+        if (!stats.isFile() || stats.size > 8 * 1024 * 1024) throw new CliError(2, 'Input must be a regular file up to 8 MiB.');
+        buffer = await handle.readFile();
+      } finally { await handle.close(); }
+    }
+    if (buffer.length > 8 * 1024 * 1024) throw new CliError(2, 'Input exceeds 8 MiB.');
+    return new TextDecoder('utf-8', { fatal: true }).decode(buffer);
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw new CliError(8, 'Could not read UTF-8 input. Check the file exists and is readable.');
+  }
+}
+
+export function parseJson(text) {
+  try { return JSON.parse(text); }
+  catch { throw new CliError(2, 'Input is not valid JSON. See the command --help for a complete example.'); }
+}
+
+export function sanitize(value, key) {
+  if (typeof value === 'string') return redact(value, key);
+  if (Array.isArray(value)) return value.map((v) => sanitize(v, key));
+  if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [redact(k, key), /^(?:authorization|api[_-]?key|access[_-]?token|password|secret)$/i.test(k) ? '[REDACTED]' : sanitize(v, key)]));
+  return value;
+}
+
+export function assertNoSecrets(value, key) {
+  if (JSON.stringify(sanitize(value, key)) !== JSON.stringify(value)) throw new CliError(2, 'Input contains credential-like content. Remove credentials from data, context, and command arguments; use EPHEMERIS_API_KEY only.');
+}
+
+export async function reserveOutput(file) {
+  if (!file || file === '-') return null;
+  try { return { file, handle: await open(file, 'wx', 0o600), complete: false }; }
+  catch { throw new CliError(8, 'Cannot create output file. Choose a new path in an existing writable directory; existing files are never overwritten.'); }
+}
+
+export async function output(text, target) {
+  try {
+    if (target) { await target.handle.writeFile(text); await target.handle.sync(); await target.handle.close(); target.complete = true; }
+    else await new Promise((resolve, reject) => process.stdout.write(text, (err) => err ? reject(err) : resolve()));
+  } catch { throw new CliError(8, 'Output write failed. For paid forecasts retain the retry key and check stdout for the recovered artifact.'); }
+}
+
+export async function cleanup(target) {
+  if (!target || target.complete) return;
+  await target.handle.close().catch(() => {});
+  await unlink(target.file).catch(() => {});
+}
+
+export async function forecastSchema(kind = 'request') {
+  if (!['request', 'artifact', 'prepared', 'data', 'submission'].includes(kind)) throw new CliError(2, '--kind must be request, artifact, prepared, data, or submission.');
+  if (kind !== 'request') return JSON.parse(await readFile(new URL(`../schema/${kind}-v1.json`, import.meta.url), 'utf8'));
+  const spec = JSON.parse(await readFile(new URL('../schema/openapi.json', import.meta.url), 'utf8'));
+  const definitions = Object.fromEntries(Object.entries(spec.components.schemas).map(([n, schema]) => [n, JSON.parse(JSON.stringify(schema).replaceAll('#/components/schemas/', '#/$defs/'))]));
+  return { $schema: 'https://json-schema.org/draft/2020-12/schema', $ref: '#/$defs/ForecastRequest', $defs: definitions };
+}

package/src/plot.js

@@ -0,0 +1,78 @@
+import { selectForecast } from './artifact.js';
+import { fail } from './data.js';
+import { integer } from './validate.js';
+
+const xml = (v) => String(v).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g, '');
+const number = (n) => Number(n.toPrecision(5)).toString();
+
+function runs(points) {
+  const output = []; let current = [];
+  for (const p of points) { if (p === null) { if (current.length) output.push(current); current = []; } else current.push(p); }
+  if (current.length) output.push(current);
+  return output;
+}
+
+export function plot(value, options) {
+  const { artifact: a, history: fullHistory, context, quantiles, i, j } = selectForecast(value, options);
+  const median = quantiles['0.5'];
+  if (!median) fail('Plot requires a returned 0.5 quantile; no median is invented. The saved artifact remains usable.');
+  const window = options.history === 'all' ? fullHistory.length : options.history === undefined ? Math.max(24, median.length * 2) : integer(options.history, '--history', 1, 100000);
+  const history = fullHistory.slice(-window);
+  const omittedHistory = fullHistory.length - history.length;
+  const levels = Object.keys(quantiles).map(Number).sort((a, b) => a - b);
+  let pairs;
+  if ((options.lower === undefined) !== (options.upper === undefined)) fail('Specify --lower and --upper together.');
+  if (options.lower !== undefined) {
+    const low = Number(options.lower), high = Number(options.upper);
+    if (!(low > 0 && low < high && high < 1) || !quantiles[low] || !quantiles[high]) fail('Band levels must exist in the saved result and satisfy 0 < lower < upper < 1.');
+    pairs = [[low, high]];
+  } else pairs = levels.filter((q) => q < 0.5).flatMap((low) => { const high = levels.find((q) => Math.abs(q - (1 - low)) < 1e-10); return high === undefined ? [] : [[low, high]]; });
+  const all = [...history, ...median, ...pairs.flatMap(([l, u]) => [...quantiles[l], ...quantiles[u]])].filter((v) => v !== null);
+  let min = all.reduce((m, v) => Math.min(m, v), Infinity), max = all.reduce((m, v) => Math.max(m, v), -Infinity);
+  // Scale first so even extreme finite values cannot overflow the SVG coordinates.
+  const scale = Math.max(Math.abs(min), Math.abs(max), 1);
+  min /= scale; max /= scale;
+  const span = max - min || 1;
+  min -= span * 0.08; max += span * 0.08;
+  const left = 100, right = 1020, top = 100, bottom = 500;
+  const total = history.length + median.length;
+  const x = (index) => left + index / Math.max(total - 1, 1) * (right - left);
+  const y = (v) => bottom - (v / scale - min) / (max - min) * (bottom - top);
+  const line = (points, color) => runs(points).map((r) => r.length === 1 ? `<circle cx="${r[0][0]}" cy="${r[0][1]}" r="3" fill="${color}"/>` : `<polyline points="${r.map((p) => p.join(',')).join(' ')}" fill="none" stroke="${color}" stroke-width="2.5"/>`).join('');
+  const boundary = x(history.length - 0.5);
+  let missingBands = 0;
+  const bands = pairs.map(([low, high], pairIndex) => {
+    const points = median.map((_, k) => {
+      const l = quantiles[low][k], u = quantiles[high][k];
+      if (l === null || u === null || l > u) { missingBands++; return null; }
+      return [x(history.length + k), y(l), y(u)];
+    });
+    return runs(points).map((r) => r.length === 1 ? `<line x1="${r[0][0]}" x2="${r[0][0]}" y1="${r[0][1]}" y2="${r[0][2]}" stroke="#2563eb" stroke-width="5" opacity="0.3"/>` : `<polygon points="${[...r.map((p) => [p[0], p[1]]), ...[...r].reverse().map((p) => [p[0], p[2]])].map((p) => p.join(',')).join(' ')}" fill="#2563eb" opacity="${0.1 + pairIndex * 0.035}"/>`).join('');
+  }).join('');
+  const labels = context.future_axis.kind === 'timestamps' ? [...context.timestamps.slice(omittedHistory), ...context.future_axis.values] : [...history.map((_, k) => `${k - history.length + 1}`), ...median.map((_, k) => `+${k + 1}`)];
+  const ticks = [...new Set([0, Math.max(0, history.length - 1), history.length, total - 1])];
+  const bandNames = pairs.map(([l, u]) => `q${l}–q${u} (${number((u - l) * 100)}% nominal mass)`);
+  const bandRows = bandNames.length ? Array.from({ length: Math.ceil(bandNames.length / 2) }, (_, k) => bandNames.slice(k * 2, k * 2 + 2).join('; ')) : ['none available'];
+  const extraHeight = (bandRows.length - 1) * 20;
+  const title = context.target_description || `Forecast — series ${i}, variate ${j}`;
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="1100" height="${710 + extraHeight}" viewBox="0 0 1100 ${710 + extraHeight}" role="img" aria-labelledby="title desc">
+<title id="title">${xml(title)}</title><desc id="desc">Observed history and saved marginal median forecast. Bands: ${xml(bandNames.join('; ') || 'none available')}. Missing values break lines; crossed or missing bands are omitted. No inference was run.</desc>
+<rect width="1100" height="${710 + extraHeight}" fill="#fff"/>
+<g font-family="system-ui, sans-serif" fill="#172033">
+<text x="100" y="35" font-size="22">${xml(title)}</text>
+<text x="100" y="65" font-size="13">Unit: ${xml(context.unit ?? 'unknown')} · Measurement: ${xml(context.measurement ?? 'unknown')} · Timezone: ${xml(context.timezone ?? 'unspecified')}</text>
+${Array.from({ length: 5 }, (_, k) => { const v = min + k / 4 * (max - min); const yy = bottom - k / 4 * (bottom - top); const label = Number.isFinite(v * scale) ? number(v * scale) : `${number(v)} × ${scale.toExponential(1)}`; return `<line x1="${left}" x2="${right}" y1="${yy}" y2="${yy}" stroke="#e5e7eb"/><text x="90" y="${yy + 4}" text-anchor="end" font-size="12">${xml(label)}</text>`; }).join('')}
+${bands}
+${line(history.map((v, k) => [x(k), y(v)]), '#475569')}
+${line(median.map((v, k) => v === null ? null : [x(history.length + k), y(v)]), '#1d4ed8')}
+<line x1="${boundary}" x2="${boundary}" y1="90" y2="500" stroke="#64748b" stroke-dasharray="5 5"/><text x="${Math.min(boundary + 8, 900)}" y="92" font-size="12">Forecast boundary</text>
+${ticks.map((k, n) => `<text x="${x(k)}" y="${525 + (n % 2) * 18}" text-anchor="${n === 0 ? 'start' : n === ticks.length - 1 ? 'end' : 'middle'}" font-size="11">${xml(labels[k])}</text>`).join('')}
+<text x="100" y="575" font-size="13">${context.future_axis.kind === 'timestamps' ? 'Date/time on the recorded sampling grid' : 'Sampling steps relative to the last observation (0); reliable future dates unavailable'}</text>
+<text x="100" y="602" font-size="13">Observed history (grey) · Marginal median q0.5 (blue)</text>
+${bandRows.map((row, k) => `<text x="100" y="${626 + k * 20}" font-size="12">${k === 0 ? 'Bands: ' : ''}${xml(row)}</text>`).join('')}
+<text x="100" y="${650 + extraHeight}" font-size="12">Nominal quantiles do not establish calibrated coverage. Cumulative intervals and peak probabilities are not shown.</text>
+<text x="100" y="${674 + extraHeight}" font-size="12">History shown: ${history.length} of ${fullHistory.length}; ${omittedHistory} older observations outside view. Full history retained in artifact; model context may differ.</text>
+<text x="100" y="${695 + extraHeight}" font-size="11">Missing median steps: ${median.filter((v) => v === null).length}; omitted band points: ${missingBands}. Use --history all to show every submitted observation.</text>
+</g></svg>\n`;
+}

package/src/render.js

@@ -0,0 +1,20 @@
+import { extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { plot } from './plot.js';
+import { CliError } from './errors.js';
+
+export async function renderPlot(artifact, options) {
+  const extension = options.output && options.output !== '-' ? extname(options.output).slice(1).toLowerCase() : '';
+  const format = options.format ?? (extension || 'svg');
+  if (!['png', 'svg'].includes(format)) throw new CliError(2, 'Plot format must be png or svg.', { option: '--format', expected: 'png|svg', next_action: 'Use --output forecast.png or --output forecast.svg.' });
+  if (extension && extension !== format) throw new CliError(2, 'Plot filename extension conflicts with its format.', { option: '--output', expected: `.${format}`, next_action: `Choose a new .${format} output path.` });
+  if (format === 'png' && (!options.output || options.output === '-') && process.stdout.isTTY) throw new CliError(2, 'PNG is binary. Choose --output forecast.png or pipe stdout to a file.');
+  const svg = plot(artifact, options);
+  if (format === 'svg') return svg;
+  try {
+    const { Resvg } = await import('@resvg/resvg-js');
+    return new Resvg(svg, { font: { loadSystemFonts: false, fontFiles: [fileURLToPath(new URL('../assets/DejaVuSans.ttf', import.meta.url))], defaultFontFamily: 'DejaVu Sans', sansSerifFamily: 'DejaVu Sans' } }).render().asPng();
+  } catch {
+    throw new CliError(8, 'PNG rendering failed. Reinstall the package with its platform dependencies, or use --format svg --output forecast.svg. The saved forecast is unchanged.');
+  }
+}

package/src/submission.js

@@ -0,0 +1,49 @@
+import { mkdir, open } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { prepare, fingerprint } from './artifact.js';
+import { baseUrl } from './client.js';
+import { CliError } from './errors.js';
+import { reserveOutput, output, cleanup } from './io.js';
+
+export function readSubmission(value) {
+  if (value?.kind !== 'ephemeris.submission' || value.schema_version !== '1') throw new CliError(2, 'Expected an ephemeris.submission v1 receipt. Use the receipt saved before submission.');
+  if (typeof value.idempotency_key !== 'string' || !/^[A-Za-z0-9._:-]{8,128}$/.test(value.idempotency_key)) throw new CliError(2, 'Receipt has an invalid idempotency key.');
+  if (typeof value.origin !== 'string') throw new CliError(2, 'Receipt is missing its service origin.');
+  const origin = baseUrl(value.origin);
+  const prepared = prepare(value.prepared, {});
+  if (fingerprint(prepared.request) !== value.request_sha256) throw new CliError(2, 'Receipt request integrity check failed. Restore the original receipt; do not guess the submitted request.');
+  return { prepared, origin, idempotencyKey: value.idempotency_key };
+}
+
+export async function saveSubmission({ prepared, origin, idempotencyKey, file, outputFile }) {
+  let path = file;
+  if (!path && outputFile && outputFile !== '-') path = `${outputFile}.submission.json`;
+  if (!path) {
+    const directory = resolve('.ephemeris', 'submissions');
+    try { await mkdir(directory, { recursive: true, mode: 0o700 }); }
+    catch { throw new CliError(8, 'Cannot create the receipt directory. Choose a writable --receipt path; no forecast was submitted.'); }
+    path = resolve(directory, `${randomUUID()}.json`);
+  }
+  if (path === '-') throw new CliError(2, '--receipt must be a local file path, not stdout.');
+  path = resolve(path);
+  const receipt = {
+    kind: 'ephemeris.submission', schema_version: '1', created_at: new Date().toISOString(),
+    origin, idempotency_key: idempotencyKey, request_sha256: fingerprint(prepared.request), prepared,
+    status: 'completion_unknown',
+    disclosure: 'Contains full submitted history and local context, never credentials. Written before network access; does not prove submission or completion. Resume uses this origin, request, and key; server retention rules apply.',
+  };
+  let target;
+  try {
+    target = await reserveOutput(path);
+    await output(`${JSON.stringify(receipt, null, 2)}\n`, target);
+    // Persist the directory entry as well as the file before issuing a paid POST.
+    if (process.platform !== 'win32') {
+      const directory = await open(dirname(path), 'r');
+      try { await directory.sync(); } finally { await directory.close(); }
+    }
+  } catch (error) {
+    throw new CliError(8, 'Cannot persist the submission receipt. No forecast was submitted. Choose a new writable --receipt path.', { receipt_path: path });
+  } finally { await cleanup(target); }
+  return path;
+}

package/src/time.js

@@ -0,0 +1,95 @@
+// Conservative calendar semantics: preserve uncertainty instead of guessing dates.
+import { CliError } from './errors.js';
+
+export function frequency(value) {
+  if (typeof value !== 'string') return null;
+  if (value === 'D') return { kind: 'day', step: 86400000, label: 'D' };
+  if (value === 'W') return { kind: 'day', step: 604800000, label: 'W' };
+  if (value === 'MS') return { kind: 'month', label: 'MS' };
+  const m = /^(\d+)?(s|min|h|H)$/.exec(value);
+  if (!m) return null;
+  const step = Number(m[1] || 1) * ({ s: 1000, min: 60000, h: 3600000, H: 3600000 })[m[2]];
+  return Number.isSafeInteger(step) && step > 0 ? { kind: 'fixed', step, label: value } : null;
+}
+
+export function checkZone(zone) {
+  if (zone == null) return;
+  try { new Intl.DateTimeFormat('en', { timeZone: zone }); }
+  catch { throw new CliError(2, 'timezone must be a valid IANA zone, such as Australia/Brisbane or UTC.'); }
+}
+
+export function parseTime(value) {
+  if (typeof value !== 'string') return null;
+  const m = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})?)?$/.exec(value);
+  if (!m || +m[1] < 1000) return null;
+  const [year, month, day, hour, minute, second] = m.slice(1, 7).map((x) => Number(x || 0));
+  const ms = Number((m[7] || '').padEnd(3, '0'));
+  const wall = Date.UTC(year, month - 1, day, hour, minute, second, ms);
+  const d = new Date(wall);
+  if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day || hour > 23 || minute > 59 || second > 59) return null;
+  const offset = m[8];
+  if (offset && offset !== 'Z' && (+offset.slice(1, 3) > 23 || +offset.slice(4) > 59)) return null;
+  const offsetMs = !offset || offset === 'Z' ? 0 : (offset[0] === '-' ? -1 : 1) * (+offset.slice(1, 3) * 60 + +offset.slice(4)) * 60000;
+  return { raw: value, wall, instant: wall - offsetMs, offset: offset || null, kind: !m[4] ? 'date' : offset ? 'aware' : 'naive', year, month, day, clock: value.slice(10).replace(/(Z|[+-]\d{2}:\d{2})$/, '') };
+}
+
+function zoneMatches(p, zone) {
+  if (!zone || p.kind !== 'aware') return true;
+  const parts = Object.fromEntries(new Intl.DateTimeFormat('en-GB', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', hourCycle: 'h23' }).formatToParts(p.instant).map((v) => [v.type, v.value]));
+  return +parts.year === p.year && +parts.month === p.month && +parts.day === p.day && +parts.hour === new Date(p.wall).getUTCHours() && +parts.minute === new Date(p.wall).getUTCMinutes();
+}
+
+export function timeEvidence(timestamps, declared = null, zone = null) {
+  checkZone(zone);
+  const unknown = { supplied_frequency: declared, candidate_frequency: null, effective_frequency: declared, basis: 'unestablished', invalid_timestamps: 0, duplicate_timestamps: 0, out_of_order_pairs: 0, missing_periods: null, off_grid_intervals: null, coverage: { start: null, end: null }, regular: false, reason: null };
+  if (timestamps == null) return { ...unknown, basis: declared ? 'caller_declared_without_timestamps' : 'unknown', reason: 'No timestamps supplied; coverage and missing periods are unknown.' };
+  const parsed = timestamps.map(parseTime);
+  const valid = parsed.filter(Boolean);
+  const bad = parsed.length - valid.length;
+  const mixed = new Set(valid.map((p) => p.kind)).size > 1;
+  const mismatched = valid.some((p) => !zoneMatches(p, zone));
+  const ord = (p) => p.kind === 'aware' ? p.instant : p.wall;
+  const sorted = [...valid].sort((a, b) => ord(a) - ord(b));
+  const duplicates = valid.length - new Set(valid.map(ord)).size;
+  const inversions = valid.slice(1).filter((p, i) => ord(p) < ord(valid[i])).length;
+  const base = { ...unknown, invalid_timestamps: bad, duplicate_timestamps: duplicates, out_of_order_pairs: inversions, coverage: { start: sorted[0]?.raw ?? null, end: sorted.at(-1)?.raw ?? null } };
+  if (bad || mixed || mismatched || duplicates || inversions || parsed.length < 2) return { ...base, reason: 'Need at least two valid, consistently aware, zone-consistent, unique timestamps in increasing source order.' };
+  const sameClock = valid.every((p) => p.clock === valid[0].clock);
+  const wallDiffs = valid.slice(1).map((p, i) => p.wall - valid[i].wall);
+  const diffs = valid.slice(1).map((p, i) => ord(p) - ord(valid[i]));
+  const months = valid.slice(1).map((p, i) => (p.year - valid[i].year) * 12 + p.month - valid[i].month);
+  let candidate = null;
+  if (valid.every((p) => p.day === 1) && sameClock && months.every((n) => n === 1)) candidate = 'MS';
+  else if (sameClock && wallDiffs.every((n) => n === 86400000)) candidate = 'D';
+  else if (sameClock && wallDiffs.every((n) => n === 604800000)) candidate = 'W';
+  else if (diffs.every((n) => n === diffs[0]) && diffs[0] > 0 && diffs[0] < 86400000 && diffs[0] % 1000 === 0 && valid[0].kind !== 'date') candidate = diffs[0] % 3600000 === 0 ? `${diffs[0] / 3600000}h` : diffs[0] % 60000 === 0 ? `${diffs[0] / 60000}min` : `${diffs[0] / 1000}s`;
+  const effective = declared || candidate;
+  const f = frequency(effective);
+  const evidence = { ...base, candidate_frequency: candidate, effective_frequency: effective, basis: declared ? 'caller_declared_grid' : candidate ? 'observed_regular_grid_candidate' : 'unestablished' };
+  if (!f) return { ...evidence, reason: 'Unsupported or ambiguous grid; missing periods cannot be measured. Supported: whole-second subdaily, D, W, MS.' };
+  if (f.kind === 'fixed' && (valid[0].kind === 'date' || (valid[0].kind === 'naive' && zone && zone !== 'UTC'))) return { ...evidence, reason: 'Subdaily named-zone times need explicit offsets to resolve daylight-saving ambiguity.' };
+  const steps = f.kind === 'month' ? months : (f.kind === 'day' ? wallDiffs : diffs).map((n) => n / f.step);
+  const offGrid = steps.filter((n) => !Number.isInteger(n) || n < 1).length + ((f.kind === 'month' && (!sameClock || valid.some((p) => p.day !== 1))) || (f.kind === 'day' && !sameClock) ? 1 : 0);
+  const missing = offGrid ? null : steps.reduce((n, step) => n + step - 1, 0);
+  return { ...evidence, missing_periods: missing, off_grid_intervals: offGrid, regular: offGrid === 0 && missing === 0, reason: !declared ? 'Frequency is evidence from the observed window, not proof of the intended calendar.' : null };
+}
+
+export function futureAxis(timestamps, freq, zone, horizon) {
+  const fallback = (reason) => ({ kind: 'steps', values: Array.from({ length: horizon }, (_, i) => i + 1), reason });
+  const ev = timeEvidence(timestamps, freq, zone);
+  if (!ev.regular) return fallback(ev.reason || 'History does not establish a complete regular time grid.');
+  const p = parseTime(timestamps.at(-1));
+  const f = frequency(ev.effective_frequency);
+  if (p.kind === 'aware' && f.kind !== 'fixed' && ((zone && zone !== 'UTC') || (!zone && p.offset !== 'Z'))) return fallback('Calendar projection needs verified future timezone offsets; using forecast steps. Supply a validated future timestamp grid when known.');
+  const values = [];
+  for (let i = 1; i <= horizon; i++) {
+    const wall = f.kind === 'month' ? Date.UTC(p.year, p.month - 1 + i, 1, new Date(p.wall).getUTCHours(), new Date(p.wall).getUTCMinutes(), new Date(p.wall).getUTCSeconds(), new Date(p.wall).getUTCMilliseconds()) : p.wall + i * f.step;
+    if (!Number.isFinite(wall) || Math.abs(wall) > 8640000000000000) return fallback('Dates exceed the supported calendar range.');
+    const iso = new Date(wall).toISOString();
+    if (!/^\d{4}-/.test(iso)) return fallback('Projected dates exceed the supported four-digit year range.');
+    if (p.kind === 'date') values.push(iso.slice(0, 10));
+    else if (f.kind === 'fixed' && p.kind === 'aware') values.push(new Date(p.instant + i * f.step).toISOString());
+    else values.push(iso.slice(0, -1) + (p.offset || ''));
+  }
+  return { kind: 'timestamps', values, reason: 'Projected from the recorded regular grid; future observations have not occurred.' };
+}

package/src/validate.js

@@ -0,0 +1,69 @@
+import { CliError } from './errors.js';
+
+const object = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const fail = (message, details) => { throw new CliError(2, message, details); };
+export function integer(v, name, min, max) {
+  const details = { [name.startsWith('--') ? 'option' : 'field']: name, expected: `integer ${min}–${max}`, next_action: `Supply ${name} within the stated range. Use the command --help for units and defaults.` };
+  if (typeof v === 'string' && !/^\d+$/.test(v)) fail(`${name} must be an integer ${min}–${max}.`, details);
+  const n = typeof v === 'string' ? Number(v) : v;
+  if (!Number.isSafeInteger(n) || n < min || n > max) fail(`${name} must be an integer ${min}–${max}.`, details);
+  return n;
+}
+function numericPath(v, name, length) {
+  if (!Array.isArray(v) || !v.length || !v.every((x) => typeof x === 'number' && Number.isFinite(x))) {
+    fail(`${name} must be a non-empty array of finite numbers.`);
+  }
+  if (length !== undefined && v.length !== length) fail(`${name} must contain ${length} values.`);
+}
+
+export function validateForecast(body) {
+  if (!object(body)) fail('Input must be a JSON request object. See ephemeris forecast --help.');
+  if (!['route', 'ensemble', 'explicit'].includes(body.mode)) fail('mode must be route, ensemble, or explicit.');
+  if (body.mode === 'explicit' && (typeof body.model !== 'string' || !body.model.trim())) fail('explicit mode requires model; discover names with ephemeris models list.');
+  if (body.model !== undefined && (typeof body.model !== 'string' || !body.model.trim())) fail('model must be a non-empty string.');
+  if (body.freq !== undefined) fail('Put freq inside each series object: series[0].freq, not at the request root.');
+  if (!Array.isArray(body.series) || !body.series.length || body.series.length > 64) fail('series must contain 1–64 objects with values and optional freq.');
+  for (const field of ['horizon', 'context_len', 'top_k']) {
+    if (body[field] !== undefined && body[field] !== null && typeof body[field] !== 'number') fail(`${field} must be a JSON number, not a string.`);
+  }
+  const horizon = integer(body.horizon ?? 64, 'horizon', 1, 4096);
+  if (body.horizon === null || body.context_len === null) fail('horizon and context_len must be integers when provided.');
+  integer(body.context_len ?? 256, 'context_len', 1, 16384);
+  let slots = 0;
+  for (const [i, entry] of body.series.entries()) {
+    const name = `series[${i}]`;
+    if (!object(entry)) fail(`${name} must be an object: {"values":[...],"freq":"H"}.`);
+    if (!Array.isArray(entry.values) || !entry.values.length) fail(`${name}.values must be a non-empty array.`);
+    const paths = Array.isArray(entry.values[0]) ? entry.values : [entry.values];
+    for (const path of paths) numericPath(path, `${name}.values`, paths[0].length);
+    slots += paths.length;
+    if (entry.freq !== undefined && (typeof entry.freq !== 'string' || !entry.freq.trim())) fail(`${name}.freq must be a non-empty string.`);
+    if (entry.covariates !== undefined) {
+      const cov = entry.covariates;
+      if (!object(cov) || !object(cov.past)) fail(`${name}.covariates needs a past object.`);
+      for (const side of ['past', 'future']) {
+        if (side === 'future' && cov.future === undefined) continue;
+        if (!object(cov[side]) || Object.keys(cov[side]).length > 16) fail(`${name}.covariates.${side} must have at most 16 channels.`);
+        for (const [channel, values] of Object.entries(cov[side])) {
+          if (!channel.trim()) fail('Covariate names must be non-empty.');
+          numericPath(values, `${name}.covariates.${side}.${channel}`, side === 'past' ? paths[0].length : horizon);
+          if (side === 'future' && !Object.hasOwn(cov.past, channel)) fail(`Future covariate ${channel} needs matching past history.`);
+        }
+      }
+    }
+  }
+  if (slots > 256) fail('Request exceeds 256 total variates.');
+  if (body.quantiles !== undefined) {
+    const q = body.quantiles;
+    if (!Array.isArray(q) || !q.length || q.length > 21 || q.some((v) => typeof v !== 'number' || !Number.isFinite(v) || v <= 0 || v >= 1) || new Set(q).size !== q.length) {
+      fail('quantiles must contain 1–21 unique numbers strictly between 0 and 1; use [0.1,0.5,0.9] for a central 80% interval.', { field: '/quantiles', expected: '1–21 unique JSON numbers strictly between 0 and 1', next_action: 'Correct the requested levels and run forecast run --dry-run before submitting. For median and a central nominal 80% interval use --quantiles 0.1,0.5,0.9.' });
+    }
+  }
+  if (slots * horizon * (body.quantiles?.length ?? 21) > 120000) fail('Total variates × horizon × quantile count must not exceed 120000 (omitted quantiles count as 21). Reduce request dimensions explicitly; do not silently truncate data.', { field: '/series', next_action: 'Reduce the requested horizon/quantiles or explicitly partition series, then dry-run again.' });
+  if (body.top_k !== undefined && body.top_k !== null) {
+    if (body.mode !== 'ensemble') fail('top_k requires ensemble mode.');
+    integer(body.top_k, 'top_k', 1, 16);
+  }
+  if (body.combine !== undefined && !['mixture', 'vincentize'].includes(body.combine)) fail('combine must be mixture or vincentize.');
+  return body;
+}

package/src/version.js

@@ -0,0 +1,17 @@
+import { readFileSync } from 'node:fs';
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+export const VERSION = pkg.version;
+export function versionInfo() {
+  let commit = null;
+  try {
+    const build = JSON.parse(readFileSync(new URL('../build-info.json', import.meta.url), 'utf8'));
+    if (build.version === VERSION && /^[a-f0-9]{40}$/.test(build.commit)) commit = build.commit;
+  } catch { /* Source checkouts have no stamped build; do not guess. */ }
+  return {
+    component: 'ephemeris-cli', version: VERSION, build_commit: commit,
+    artifact_schema_versions: {
+      'ephemeris.forecast': ['1'], 'ephemeris.data': ['1'],
+      'ephemeris.request': ['1'], 'ephemeris.submission': ['1'],
+    },
+  };
+}