ephemeris-cli 0.0.0-stage → 0.4.0

package/src/artifact.js

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+import { hash, isObject, fail, metadata, validateSnapshot } from './data.js';
+import { integer, validateForecast } from './validate.js';
+import { timeEvidence, futureAxis } from './time.js';
+
+export function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (isObject(value)) return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
+  return JSON.stringify(value);
+}
+
+export function fingerprint(value) { return hash(canonical(value)); }
+
+export function contextFor(request, supplied = {}) {
+  if (!isObject(supplied) || Object.keys(supplied).some((k) => !['series', 'scenario_assumptions', 'snapshot_id', 'source'].includes(k))) fail('Local context accepts series, scenario_assumptions, snapshot_id, and source only.');
+  if (supplied.series !== undefined && (!Array.isArray(supplied.series) || supplied.series.length !== request.series.length)) fail('context.series must align one-to-one with request.series.');
+  if (supplied.scenario_assumptions !== undefined && (!Array.isArray(supplied.scenario_assumptions) || supplied.scenario_assumptions.some((v) => typeof v !== 'string' || !v.trim()))) fail('scenario_assumptions must be a list of caller-supplied statements.');
+  const horizon = request.horizon ?? 64;
+  const series = request.series.map((s, i) => {
+    const c = supplied.series?.[i] ?? {};
+    if (!isObject(c)) fail('Each context.series entry must be an object.');
+    const allowed = ['series_id', 'unit', 'timezone', 'target_description', 'measurement', 'timestamps', 'future_timestamps', 'future_covariate_roles', 'source_available_at', 'recorded_as_of'];
+    if (Object.keys(c).some((k) => !allowed.includes(k))) fail('Unknown local series context field. See forecast run --help.');
+    const info = metadata({ unit: c.unit, timezone: c.timezone, 'target-description': c.target_description, measurement: c.measurement });
+    for (const field of ['series_id', 'source_available_at', 'recorded_as_of']) if (c[field] != null && (typeof c[field] !== 'string' || !c[field].trim())) fail(`${field} must be a string or null.`);
+    const history = Array.isArray(s.values[0]) ? s.values[0] : s.values;
+    const timestamps = c.timestamps ?? null;
+    if (timestamps !== null && (!Array.isArray(timestamps) || timestamps.length !== history.length)) fail('context timestamps must align with every supplied history point.');
+    const evidence = timeEvidence(timestamps, s.freq ?? null, info.timezone);
+    if (timestamps !== null && (evidence.invalid_timestamps || evidence.duplicate_timestamps || evidence.out_of_order_pairs || !evidence.regular)) fail('Context timestamps must form a complete supported grid matching the request frequency. Otherwise omit timestamps and use forecast steps.');
+    let axis = futureAxis(timestamps, s.freq ?? null, info.timezone, horizon);
+    if (c.future_timestamps != null) {
+      if (!timestamps || !Array.isArray(c.future_timestamps) || c.future_timestamps.length !== horizon) fail('Explicit future_timestamps require history timestamps and exactly horizon entries.');
+      const combined = timeEvidence([...timestamps, ...c.future_timestamps], s.freq ?? evidence.effective_frequency, info.timezone);
+      if (!combined.regular) fail('future_timestamps must continue the history grid without gaps, duplicates, or timezone changes.');
+      axis = { kind: 'timestamps', values: c.future_timestamps, reason: 'Caller-supplied future grid validated against the history grid.' };
+    }
+    const roles = c.future_covariate_roles ?? {};
+    if (!isObject(roles) || Object.keys(roles).some((n) => !Object.hasOwn(s.covariates?.future ?? {}, n)) || Object.values(roles).some((v) => !['known_future', 'scenario_assumption', 'unspecified'].includes(v))) fail('future_covariate_roles must map submitted future channel names to known_future, scenario_assumption, or unspecified.');
+    return { ...info, series_id: c.series_id ?? null, timestamps, future_axis: axis, frequency_evidence: evidence,
+      source_available_at: c.source_available_at ?? null, recorded_as_of: c.recorded_as_of ?? null,
+      future_covariate_roles: Object.fromEntries(Object.keys(s.covariates?.future ?? {}).map((name) => [name, roles[name] ?? 'unspecified'])) };
+  });
+  return { series, scenario_assumptions: supplied.scenario_assumptions ?? [], snapshot_id: supplied.snapshot_id ?? null, source: supplied.source ?? null };
+}
+
+export function prepare(input, options, externalContext) {
+  let request, context;
+  if (input?.kind === 'ephemeris.data') {
+    // Verify the frozen snapshot, then validate the selected series only.
+    if (input.schema_version !== '1' || !Array.isArray(input.series) || input.snapshot_id !== hash(JSON.stringify(input.series))) fail('Snapshot version or integrity check failed.');
+    if (input.series.length > 1 && !options.series) fail('Choose --series ID from the inspection; the CLI does not guess a target.');
+    const chosen = options.series ? input.series.find((s) => s.series_id === options.series) : input.series[0];
+    if (!chosen) fail('Selected series was not found in the inspected snapshot.');
+    validateSnapshot({ ...input, series: [chosen], snapshot_id: hash(JSON.stringify([chosen])) });
+    if (externalContext) fail('An inspected snapshot already fixes its context. Reinspect the source to change metadata.');
+    request = { mode: 'route', series: [{ values: chosen.values, ...(chosen.context.frequency ? { freq: chosen.context.frequency } : {}) }] };
+    const { frequency: _frequency, ...local } = chosen.context;
+    context = { series: [{ ...local, series_id: chosen.series_id, timestamps: chosen.timestamps }], snapshot_id: input.snapshot_id, source: input.source };
+  } else if (input?.kind === 'ephemeris.request') {
+    if (input.schema_version !== '1') fail('Unsupported prepared-request version.');
+    if (externalContext) fail('Prepared requests already include context. Edit it explicitly before rerunning.');
+    request = structuredClone(input.request); context = input.context;
+  } else { request = structuredClone(input); context = externalContext; }
+  if (!isObject(request)) fail('Input must be a public API request, prepared request, or inspected snapshot.');
+  if (options.series && input?.kind !== 'ephemeris.data') fail('--series applies only to an inspected snapshot.');
+  for (const key of ['mode', 'model']) if (options[key] !== undefined) request[key] = options[key];
+  if (options.horizon !== undefined) request.horizon = integer(options.horizon, '--horizon', 1, 4096);
+  if (options['context-len'] !== undefined) request.context_len = integer(options['context-len'], '--context-len', 1, 16384);
+  if (options.quantiles !== undefined) {
+    if (!/^\s*\d*\.?\d+(?:\s*,\s*\d*\.?\d+)*\s*$/.test(options.quantiles)) fail('--quantiles must be comma-separated numbers, e.g. 0.1,0.5,0.9.');
+    request.quantiles = options.quantiles.split(',').map(Number);
+  }
+  validateForecast(request);
+  // Keep metadata and credentials out of the API even if the gateway permits extras.
+  const rootKeys = ['mode', 'model', 'series', 'horizon', 'quantiles', 'context_len', 'top_k', 'combine'];
+  if (Object.keys(request).some((k) => !rootKeys.includes(k))) fail('Unknown request field. Local metadata belongs in --context, not in the API request.');
+  for (const s of request.series) if (Object.keys(s).some((k) => !['values', 'freq', 'covariates'].includes(k))) fail('Unknown series field. Put units, timestamps, and descriptions in --context.');
+  // A prepared request stores only supplied context, so it can be reused unchanged.
+  const resolved = contextFor(request, context);
+  const local = { series: resolved.series.map(({ future_axis, frequency_evidence, ...s }) => s), scenario_assumptions: resolved.scenario_assumptions, snapshot_id: resolved.snapshot_id, source: resolved.source };
+  // Explicit future timestamps must survive a dry-run/retry round trip.
+  local.series.forEach((s, i) => { if (context?.series?.[i]?.future_timestamps) s.future_timestamps = context.series[i].future_timestamps; });
+  return { kind: 'ephemeris.request', schema_version: '1', request, context: local, disclosure: 'Includes the full submitted input history. Context is local and is not sent to the API.' };
+}
+
+export function createArtifact(prepared, response, transport) {
+  return { kind: 'ephemeris.forecast', schema_version: '1', artifact_id: randomUUID(), created_at: new Date().toISOString(),
+    request: prepared.request, request_sha256: fingerprint(prepared.request), response,
+    context: contextFor(prepared.request, prepared.context), transport,
+    disclosure: { input_history_included: true, context_sent_to_api: false, credentials_included: false, provider_input_note: 'All submitted history is saved. The service may truncate it using context_len and model context limits.' },
+    interoperability: { gnomon_import: 'not_implemented', recorded_in_ledger: false, identity_basis: 'local artifact UUID and request SHA-256; hashes are not authenticity signatures' } };
+}
+
+export function readArtifact(value) {
+  if (value?.kind !== 'ephemeris.forecast' || value.schema_version !== '1') fail('Expected a version 1 Ephemeris forecast artifact from forecast run.');
+  validateForecast(value.request);
+  if (fingerprint(value.request) !== value.request_sha256) fail('Artifact request integrity check failed.');
+  if (!isObject(value.context) || !Array.isArray(value.context.series) || value.context.series.length !== value.request.series.length) fail('Artifact context must align with the request.');
+  // Validate serialized context again; do not trust cached axes in a hand-edited file.
+  const supplied = { ...value.context, series: value.context.series.map(({ future_axis, frequency_evidence, ...s }) => ({ ...s, ...(future_axis?.kind === 'timestamps' ? { future_timestamps: future_axis.values } : {}) })) };
+  const context = contextFor(value.request, supplied);
+  const rows = value.response?.forecasts;
+  if (!Array.isArray(rows) || rows.length !== value.request.series.length) fail('Saved response has malformed/missing forecast rows. The original artifact remains intact; no inference is repeated.');
+  const horizon = value.request.horizon ?? 64;
+  rows.forEach((row, i) => {
+    if (!isObject(row?.quantiles) || !Object.keys(row.quantiles).length) fail('Saved forecast has no quantile arrays.');
+    const multivariate = Array.isArray(value.request.series[i].values[0]);
+    const count = multivariate ? value.request.series[i].values.length : 1;
+    const levels = Object.keys(row.quantiles).map(Number);
+    if (levels.some((q) => !Number.isFinite(q) || q <= 0 || q >= 1) || new Set(levels).size !== levels.length) fail('Saved forecast has invalid or duplicate quantile levels.');
+    for (const array of Object.values(row.quantiles)) {
+      const paths = multivariate ? array : [array];
+      if (!Array.isArray(paths) || paths.length !== count || paths.some((p) => !Array.isArray(p) || p.length !== horizon || p.some((v) => v !== null && (typeof v !== 'number' || !Number.isFinite(v))))) fail('Saved forecast shape does not match horizon and variates; null denotes missing output.');
+    }
+  });
+  return { ...value, context };
+}
+
+export function selectForecast(artifact, options) {
+  const a = readArtifact(artifact);
+  if (a.request.series.length > 1 && options['series-index'] === undefined) fail('Choose --series-index for a multi-series artifact.');
+  const i = integer(options['series-index'] ?? '0', '--series-index', 0, a.request.series.length - 1);
+  const values = a.request.series[i].values;
+  const multi = Array.isArray(values[0]);
+  if (multi && values.length > 1 && options['variate-index'] === undefined) fail('Choose --variate-index for a multivariate artifact.');
+  const j = integer(options['variate-index'] ?? '0', '--variate-index', 0, multi ? values.length - 1 : 0);
+  return { artifact: a, i, j, history: multi ? values[j] : values, context: a.context.series[i],
+    quantiles: Object.fromEntries(Object.entries(a.response.forecasts[i].quantiles).map(([q, array]) => [Number(q), multi ? array[j] : array])),
+    pointer: `/response/forecasts/${i}/quantiles`, history_pointer: `/request/series/${i}/values${multi ? `/${j}` : ''}` };
+}

package/src/cli.js

@@ -0,0 +1,123 @@
+import { versionInfo } from './version.js';
+import { parseArgs } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { commands, common, help, VERSION } from './commands.js';
+import { CliError } from './errors.js';
+import { baseUrl, request } from './client.js';
+import { integer } from './validate.js';
+import { inspect } from './data.js';
+import { prepare, createArtifact } from './artifact.js';
+import { describe } from './describe.js';
+import { renderPlot } from './render.js';
+import { argumentError } from './arguments.js';
+import { readSubmission, saveSubmission } from './submission.js';
+import { resolve } from 'node:path';
+import { readText, parseJson, sanitize, assertNoSecrets, reserveOutput, output, cleanup, forecastSchema } from './io.js';
+
+const definitions = Object.assign({}, common, ...Object.values(commands).map((c) => c.options), { version: { type: 'boolean' } });
+const options = Object.fromEntries(Object.entries(definitions).map(([k, v]) => [k, { type: v.type, ...(v.short ? { short: v.short } : {}) }]));
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+export async function main(argv, env = process.env) {
+  const key = (env.EPHEMERIS_API_KEY || '').trim();
+  const controller = new AbortController();
+  const interrupt = () => controller.abort();
+  let target, idempotencyKey, paidArtifact, receiptPath, resumedOrigin;
+  const log = (data) => process.stderr.write(`${JSON.stringify(sanitize(data, key))}\n`);
+  try {
+    let parsed;
+    try { parsed = parseArgs({ args: argv, options, allowPositionals: true, strict: true, tokens: true }); }
+    catch (error) { throw argumentError(error, argv, options); }
+    const { values, positionals, tokens } = parsed;
+    assertNoSecrets(values, key);
+    const seen = new Set();
+    for (const token of tokens.filter((t) => t.kind === 'option')) { if (seen.has(token.name)) throw new CliError(2, 'Repeated options are not supported. Supply each option once.'); seen.add(token.name); }
+    if (values.version && !positionals.length) { await output(`${VERSION}\n`); return 0; }
+    let name = positionals.join(' ');
+    if (name === 'forecast' && (values.input !== undefined || values.resume !== undefined)) name = 'forecast run';
+    if (!name && (values.help || !argv.length)) { await output(help()); return 0; }
+    if (!commands[name] && ['models', 'usage', 'auth', 'schema', 'data', 'forecast'].includes(name)) {
+      if (!values.help && Object.keys(values).length) throw new CliError(2, `Choose a subcommand. Run ephemeris ${name} --help.`);
+      await output(`Usage: ephemeris ${name} <command> [options]\n\n${Object.keys(commands).filter((n) => n.startsWith(`${name} `)).map((n) => `  ${n} — ${commands[n].summary}\n  Run ephemeris ${n} --help`).join('\n')}\n`);
+      return 0;
+    }
+    const command = commands[name];
+    if (!command) throw new CliError(2, 'Unknown or missing command. Run ephemeris --help.');
+    for (const option of Object.keys(values)) if (!Object.hasOwn(common, option) && !Object.hasOwn(command.options, option)) throw new CliError(2, `--${option} is not supported for ${name}.`, { option: `--${option}`, next_action: `Run ephemeris ${name} --help.` });
+    if (values.help) { await output(help(name)); return 0; }
+    let data, textResult, body, prepared, path = command.path;
+    if (['data inspect', 'forecast run', 'forecast describe', 'forecast plot'].includes(name)) {
+      if (name === 'forecast run' && values.resume !== undefined) {
+        const forbidden = ['input', 'context', 'series', 'mode', 'model', 'horizon', 'quantiles', 'context-len', 'idempotency-key', 'base-url', 'receipt'];
+        const conflict = forbidden.find((option) => values[option] !== undefined);
+        if (conflict) throw new CliError(2, '--resume fixes the saved origin, request, context, and key; overrides are not allowed.', { option: `--${conflict}`, next_action: 'Use --resume alone with --output, --timeout, or --dry-run.' });
+        if (values.resume === '-') throw new CliError(2, '--resume requires a saved receipt file path.');
+      }
+      const text = await readText(values.resume ?? values.input);
+      assertNoSecrets(text, key);
+      if (name === 'data inspect') data = inspect(text, values, values.input);
+      else {
+        const input = parseJson(text); assertNoSecrets(input, key);
+        if (name === 'forecast run') {
+          if (values.context === '-' && values.input === '-') throw new CliError(2, 'Only one input may use stdin.');
+          const context = values.context ? parseJson(await readText(values.context)) : undefined;
+          assertNoSecrets(context, key);
+          if (values.resume !== undefined) {
+            const saved = readSubmission(input);
+            prepared = saved.prepared; resumedOrigin = saved.origin; idempotencyKey = saved.idempotencyKey;
+            receiptPath = resolve(values.resume);
+          } else {
+            prepared = prepare(input, values, context);
+            idempotencyKey = values['idempotency-key'] ?? randomUUID();
+          }
+          body = prepared.request;
+          if (!/^[A-Za-z0-9._:-]{8,128}$/.test(idempotencyKey)) throw new CliError(2, '--idempotency-key must be 8–128 letters, digits, dots, underscores, colons, or hyphens.');
+          assertNoSecrets(idempotencyKey, key);
+          if (values['dry-run']) data = prepared;
+        } else if (name === 'forecast describe') data = describe(input, values);
+        else textResult = await renderPlot(input, values);
+      }
+    }
+    if (name === 'version') data = versionInfo();
+    if (name === 'schema forecast') data = await forecastSchema(values.kind);
+    if (name === 'usage list') path += `?limit=${integer(values.limit ?? '50', '--limit', 1, 200)}&offset=${integer(values.offset ?? '0', '--offset', 0, Number.MAX_SAFE_INTEGER)}`;
+    const needsNetwork = data === undefined && textResult === undefined && !(name === 'auth status' && !values.verify);
+    let origin, timeout;
+    if (needsNetwork || name === 'auth status') {
+      origin = baseUrl(resumedOrigin ?? values['base-url'] ?? env.EPHEMERIS_BASE_URL);
+      timeout = integer(values.timeout ?? '300', '--timeout', 1, 3600);
+      if (needsNetwork && (!key || /\s/.test(key))) throw new CliError(3, 'Set EPHEMERIS_API_KEY to your dashboard API key. Run ephemeris auth status --help.');
+      if (!needsNetwork) data = { configured: Boolean(key), verified: false, source: key ? 'EPHEMERIS_API_KEY' : null, base_url: origin };
+    }
+    target = await reserveOutput(values.output);
+    if (needsNetwork) {
+      process.on('SIGINT', interrupt); process.on('SIGTERM', interrupt);
+      if (name === 'forecast run') {
+        receiptPath ??= await saveSubmission({ prepared, origin, idempotencyKey, file: values.receipt, outputFile: values.output });
+        if (controller.signal.aborted) throw new CliError(130, 'Interrupted before submission. The receipt is available for recovery.');
+        log({ event: 'forecast_submission', idempotency_key: idempotencyKey, receipt_path: receiptPath, recovery: { command: 'ephemeris forecast run', args: ['--resume', receiptPath, '--output', 'recovered.json'] }, hint: 'Receipt contains full input history. Resume reuses the saved origin, request, and key; server retention rules apply.' });
+      }
+      const transport = {};
+      const response = await request({ origin, path: name === 'auth status' ? '/api/v1/balance' : path, method: command.method, key, body, idempotencyKey, timeout, signal: controller.signal, receipt: transport });
+      if (name === 'auth status') data = { configured: true, verified: true, source: 'EPHEMERIS_API_KEY', base_url: origin };
+      else if (name === 'forecast run') {
+        const safe = sanitize(response, key);
+        data = createArtifact(prepared, safe, { origin, idempotency_key: idempotencyKey, ...sanitize(transport, key), credentials_redacted: JSON.stringify(safe) !== JSON.stringify(response) });
+        paidArtifact = data;
+      } else data = sanitize(response, key);
+    }
+    await output(textResult ?? json(sanitize(data, key)), target);
+    return 0;
+  } catch (error) {
+    if (paidArtifact && target) {
+      try { await output(json(sanitize(paidArtifact, key))); log({ event: 'artifact_recovered_on_stdout', hint: 'Save stdout as JSON. Description and plotting can be retried offline.' }); }
+      catch { log({ event: 'artifact_output_failed', hint: 'Retry with the same idempotency key and identical input; server retention rules apply.' }); }
+    }
+    const code = error instanceof CliError ? error.code : 7;
+    log({ error: { code, message: error instanceof CliError ? error.message : 'Unexpected local failure.', ...(error.details ?? {}), ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}), ...(receiptPath ? { receipt_path: receiptPath, next_action: 'Run ephemeris forecast run --resume <receipt_path> --output <new-file>. The server may have completed the original request; retention rules apply.' } : {}) } });
+    return code;
+  } finally {
+    await cleanup(target);
+    process.removeListener('SIGINT', interrupt); process.removeListener('SIGTERM', interrupt);
+  }
+}

package/src/client.js

@@ -0,0 +1,50 @@
+import { CliError } from './errors.js';
+import { DEFAULT_URL, VERSION } from './commands.js';
+
+export function baseUrl(value = DEFAULT_URL) {
+  let url;
+  try { url = new URL(value); } catch { throw new CliError(2, 'Invalid base URL; use an HTTPS service origin.'); }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
+    throw new CliError(2, 'Base URL must be an HTTPS origin without credentials, path, query, or fragment. HTTP is allowed only for loopback development.');
+  }
+  return url.origin;
+}
+
+export async function request({ origin, path, method = 'GET', key, body, idempotencyKey, timeout, signal, receipt }) {
+  const headers = { accept: 'application/json', authorization: `Bearer ${key}`, 'user-agent': `ephemeris-cli/${VERSION}` };
+  if (body !== undefined) headers['content-type'] = 'application/json';
+  if (idempotencyKey) headers['idempotency-key'] = idempotencyKey;
+  let response, text;
+  try {
+    response = await fetch(`${origin}${path}`, {
+      method, headers, body: body === undefined ? undefined : JSON.stringify(body),
+      // Do not forward credentials to a redirect destination or replay a billed POST.
+      redirect: 'manual',
+      signal: AbortSignal.any([AbortSignal.timeout(timeout * 1000), signal]),
+    });
+    text = await response.text();
+  } catch {
+    if (signal.aborted) throw new CliError(130, 'Interrupted. Forecast completion may be unknown; retain the idempotency key.');
+    throw new CliError(6, 'Network request failed or timed out. Forecast completion may be unknown; retry with the same idempotency key and identical input.');
+  }
+  const details = {
+    http_status: response.status,
+    request_id: response.headers.get('x-request-id'),
+    retry_after: response.headers.get('retry-after'),
+  };
+  if (receipt) Object.assign(receipt, details, { idempotency_replayed: response.headers.get('idempotency-replayed') });
+  let data;
+  try { data = JSON.parse(text); } catch {
+    // Do not echo arbitrary HTML, proxy errors, or credentials.
+    data = null;
+  }
+  if (!response.ok) {
+    const status = response.status;
+    const code = [401, 403].includes(status) ? 3 : status === 402 ? 4 : [409, 429].includes(status) ? 5 : status >= 500 || status === 408 ? 6 : status === 400 || status === 422 ? 2 : 7;
+    const hints = { 2: 'Check the request with forecast --help.', 3: 'Check EPHEMERIS_API_KEY and its permissions.', 4: 'Add credits in the dashboard.', 5: 'Inspect Retry-After and the API error; preserve the key for identical forecast retries.', 6: 'Service unavailable; preserve the key for identical forecast retries.', 7: 'Check the service origin and API compatibility.' };
+    throw new CliError(code, `API returned HTTP ${status}. ${hints[code]}`, { ...details, api_error: data });
+  }
+  if (data === null || typeof data !== 'object') throw new CliError(7, 'API returned an invalid JSON result. Preserve the idempotency key before retrying a forecast.', details);
+  return data;
+}

package/src/commands.js

@@ -0,0 +1,147 @@
+const savedExample = "# Synthetic saved result for this offline example; not live predictions.\ncat > example-forecast.json <<'JSON'\n{\"kind\":\"ephemeris.forecast\",\"schema_version\":\"1\",\"artifact_id\":\"00000000-0000-4000-8000-000000000001\",\"created_at\":\"2026-01-04T00:00:00Z\",\"request\":{\"mode\":\"route\",\"series\":[{\"values\":[10,12,11],\"freq\":\"D\"}],\"horizon\":2,\"quantiles\":[0.1,0.5,0.9]},\"request_sha256\":\"8737423c8f6d653c73037497414069f2c4bf07bcf2d6ffcb7c98dfe6190ca1df\",\"response\":{\"forecasts\":[{\"quantiles\":{\"0.1\":[9,10],\"0.5\":[12,13],\"0.9\":[15,16]}}]},\"context\":{\"series\":[{\"unit\":\"units\",\"timezone\":\"UTC\",\"target_description\":\"Synthetic observed sales\",\"measurement\":\"period_total\",\"series_id\":null,\"timestamps\":[\"2026-01-01\",\"2026-01-02\",\"2026-01-03\"],\"future_axis\":{\"kind\":\"timestamps\",\"values\":[\"2026-01-04\",\"2026-01-05\"],\"reason\":\"Projected from the recorded regular grid; future observations have not occurred.\"},\"frequency_evidence\":{\"supplied_frequency\":\"D\",\"candidate_frequency\":\"D\",\"effective_frequency\":\"D\",\"basis\":\"caller_declared_grid\",\"invalid_timestamps\":0,\"duplicate_timestamps\":0,\"out_of_order_pairs\":0,\"missing_periods\":0,\"off_grid_intervals\":0,\"coverage\":{\"start\":\"2026-01-01\",\"end\":\"2026-01-03\"},\"regular\":true,\"reason\":null},\"source_available_at\":null,\"recorded_as_of\":null,\"future_covariate_roles\":{}}],\"scenario_assumptions\":[],\"snapshot_id\":null,\"source\":null},\"transport\":{},\"disclosure\":{\"input_history_included\":true,\"context_sent_to_api\":false,\"credentials_included\":false,\"provider_input_note\":\"All submitted history is saved. The service may truncate it using context_len and model context limits.\"},\"interoperability\":{\"gnomon_import\":\"not_implemented\",\"recorded_in_ledger\":false,\"identity_basis\":\"local artifact UUID and request SHA-256; hashes are not authenticity signatures\"}}\nJSON";
+import { VERSION } from './version.js';
+export { VERSION };
+export const DEFAULT_URL = 'https://ephemeris.cascade.industries';
+const string = (text, short) => ({ type: 'string', text, ...(short ? { short } : {}) });
+const boolean = (text) => ({ type: 'boolean', text });
+export const common = {
+  json: boolean('JSON output (default); forecast plot emits PNG/SVG instead. Errors: JSON Lines on stderr.'),
+  output: string('Save to a NEW file; never overwrites. Default stdout; - also means stdout. Artifacts/snapshots include input history.', 'o'),
+  help: { ...boolean('Complete offline help for this command.'), short: 'h' },
+};
+const network = {
+  'base-url': string('HTTPS service origin; default EPHEMERIS_BASE_URL or https://ephemeris.cascade.industries. HTTP allowed on loopback only.'),
+  timeout: string('HTTP deadline in seconds, 1–3600; default 300. No automatic retries.'),
+};
+const input = { input: string('Required file, or - for stdin. UTF-8; maximum 8 MiB.', 'i') };
+const selection = {
+  'series-index': string('Zero-based artifact series index. Required for multiple series; otherwise 0.'),
+  'variate-index': string('Zero-based variate index. Required for multiple variates; otherwise 0. Series metadata applies to the selected variate.'),
+};
+const offline = 'Runs locally. No credentials, provider calls, credits, or network access. Does not change the input. Output is JSON unless this command specifies an image; --output writes a new file only.';
+export const commands = {
+  version: {
+    summary: 'Inspect the installed CLI version, build identity and supported local record schemas.',
+    detail: `Runs offline without credentials, inference, charges or service checks. No required inputs. JSON is the default; --json is accepted explicitly. --output writes a new file and never overwrites; stdout is the default. ephemeris --version remains the short package version only.
+
+Fields: component identifies this installed CLI; version comes from its package metadata; build_commit is the full source Git SHA stamped when a clean checkout was packed, or null when unavailable. artifact_schema_versions lists supported versions by record kind. A null commit is unknown, not evidence of an outdated install. Package, hosted MCP, bridge and artifact schema versions are independent. This command does not determine the deployed service version, latest npm version, model availability, account balance or forecast quality. Use MCP get_version for the hosted version and models list for live capabilities.
+
+Examples below need no files or API key. Exit 0 means metadata was read; invalid options exit 2; output errors exit 8. A failure causes no network operation or paid forecast; correct the option or choose a new writable output path and rerun.`,
+    options: {},
+    example: 'ephemeris version\nephemeris version --json\nephemeris version --output cli-version.json\nephemeris --version',
+  },
+  'data inspect': {
+    summary: 'Inspect selected observed columns and freeze a reusable local data snapshot.',
+    detail: `Supported: CSV/TSV with headers, JSON arrays of row objects, JSONL row objects. Select --value-column explicitly; add --time-column for time coverage and grid checks. Optional --series-column groups independent series without guessing a target. Decimal text is parsed in CSV/TSV; JSON values must be numbers. No Excel, Parquet, gzip, implicit grouping, repairs, sorting, deduplication, resampling, or interpolation.
+
+Output ephemeris.data v1 includes selected numeric history, original timestamp strings, source SHA-256, metadata, per-series readiness and reports. Missing/non-numeric cells are represented as null with separate counts and one-based source data-row numbers. Reports include observed range, frequency evidence, missing periods, duplicates, missing values, invalid cells, and zeros. Exit 0 means inspection completed, NOT ready to forecast. Check series[].report.ready_for_forecast. Counts refer to the selected observed window; no data outside it is inferred.
+
+Supported time grids: whole-second subdaily (H, 15min, 30s), D, W, and month-start MS. ISO dates or ISO datetimes only; offsets must be explicit for aware timestamps. Supply an IANA --timezone when known. Named-zone naive subdaily timestamps are ambiguous and not ready. Frequency inferred from a regular window is only a candidate; --frequency declares the intended grid. Without timestamps, missing periods/coverage remain unknown and forecasting requires declared frequency. Unsupported calendars remain unverified. A horizon counts grid steps, not calendar days.
+
+Preserve units and target meaning explicitly: period_total, period_average, or point_in_time. Observed sales are not necessarily underlying demand; zeros do not prove stockouts or lost demand. The snapshot freezes selected history; source edits do not change it. Fix bad source data explicitly and inspect again. ${offline}`,
+    options: { ...input, format: string('csv|tsv|json|jsonl. Inferred from filename extension; required for stdin.'), 'value-column': string('Required observed numeric target column; literal name.'), 'time-column': string('Optional ISO timestamp column; omitted means unknown coverage.'), 'series-column': string('Optional grouping column. Missing IDs reject; source order is preserved within each group.'), frequency: string('Declared intended sampling grid, e.g. H, 15min, D, W, MS. Default: evidence-based candidate, if unambiguous.'), unit: string('Caller-declared unit, e.g. AUD, units, kWh; default unknown. No conversion.'), timezone: string('Caller-declared IANA zone, e.g. Australia/Brisbane; default unknown. Does not silently localize ambiguous instants.'), 'target-description': string('Caller-supplied target meaning, e.g. observed daily sales; default unknown.'), measurement: string('period_total|period_average|point_in_time; default unknown.') },
+    example: `printf 'date,sales\\n2026-01-01,10\\n2026-01-02,12\\n' > example-sales.csv
+ephemeris data inspect --input example-sales.csv --time-column date --value-column sales --frequency D --unit units --measurement period_total --target-description "Synthetic observed sales" --output inspected.json
+ephemeris forecast run --input inspected.json --horizon 7 --quantiles 0.1,0.5,0.9 --dry-run
+# For real work, use actual supplied observations, units, and target meaning.`,
+  },
+  'forecast run': {
+    summary: 'Submit a forecast and save a versioned artifact; this operation spends credits.',
+    detail: `Input: an ephemeris.data v1 snapshot, an ephemeris.request v1 prepared request, or a public API request such as:
+{"mode":"route","series":[{"values":[10,12,11],"freq":"D"}],"horizon":2,"quantiles":[0.1,0.5,0.9]}
+This differs from raw Paracast. For raw CSV/TSV/JSON rows, first use data inspect. For multi-series snapshots choose --series ID. Snapshot data must be complete and regular; no silent repair.
+
+Modes: route selects automatically; ensemble blends compatible models; explicit requires model from models list. Raw/prepared JSON requires mode; snapshots default route. Explicit flags override input fields; model does not implicitly change mode. API defaults horizon=64 and context_len=256; use explicit values when required. Limits: 64 series, 256 variates, horizon 1–4096, context_len 1–16384. Each history is oldest first. Frequency belongs to each series; horizon counts sampling steps. Quantiles [0.1,0.5,0.9] give marginal median and a central nominal 80% interval, NOT proven calibrated coverage. Total variates × horizon × quantile count must not exceed 120000; omitted quantiles count as 21 for this limit. Model-specific limits may be smaller.
+
+Optional local --context JSON is separate from the API request:
+{"series":[{"unit":"units","measurement":"period_total","timezone":"UTC","target_description":"Synthetic observed sales","timestamps":["2026-01-01","2026-01-02","2026-01-03"]}]}
+context.series aligns with request.series. Allowed per-series fields: series_id, unit, measurement, timezone, target_description, timestamps, future_timestamps, future_covariate_roles, source_available_at, recorded_as_of. Missing context stays null. Timestamps must match history length and a supported regular grid. Explicit future_timestamps must continue it for horizon steps. Named-zone calendar projection may fall back to steps unless explicit future timestamps are provided. Metadata applies to all variates in its series. Future roles map channel names to known_future|scenario_assumption|unspecified. Context and assertions are retained locally, never sent as model inputs. Narrative scenario assumptions do not affect inference. No future inputs or an empty assumptions list means not supplied; it does NOT mean the model assumes zero events, no promotions, no constraints, or unchanged conditions.
+
+API series[].covariates.past numeric channels align with full history; future channels match horizon and need matching past names. Multivariate values are equal-length variate arrays. Only submitted numeric inputs affect the forecast; known future inputs and scenario assumptions must not be conflated. Use schema forecast for the wire contract. Raw requests reject unknown fields; put local context in --context.
+
+--dry-run is fully offline, needs no key, costs nothing, and outputs a reusable ephemeris.request envelope (request plus local context). Submission returns an ephemeris.forecast v1 artifact, preserving request, full submitted history, response, context, timestamps, IDs, retry key, and billing. Billing is at response.meta.billing: settled_mc is charged millicredits; balance_mc is the remaining balance at that response. All _mc fields are exact integer strings: 1000 millicredits = 1 credit, so settled_mc="100" means 100 millicredits (0.1 credits), NOT 100 credits. Preserve these units and strings; missing billing is unknown. IDs are at response.meta.gateway_request_id, response.meta.request_id, and transport.request_id when supplied. transport.credentials_redacted=false means no credential-like response content needed redaction, not that credentials were included. Credentials are excluded. No describe or plot side effects occur. API results may include null quantiles; they remain missing. Service/model context caps can shorten the history actually used.
+
+Idempotency-Key is printed BEFORE submission. A private, versioned ephemeris.submission v1 receipt is also synced to disk BEFORE the request. With --output forecast.json it defaults to forecast.json.submission.json; with stdout it uses .ephemeris/submissions/<uuid>.json in the current directory. --receipt selects another NEW path. Receipts contain the full prepared request/history/context, service origin, key, and request hash, never credentials. They remain after success or failure and do not prove completion. Existing receipts are never overwritten; a receipt write failure prevents submission. Archive or delete them explicitly when no longer needed.
+
+Recover with forecast run --resume RECEIPT --output NEW_FILE. Resume reuses the exact stored request, key, context, and origin, ignoring EPHEMERIS_BASE_URL. It rejects input/model/horizon/quantile/context/key/base-url/receipt overrides; --timeout, --output, and --dry-run are allowed. --resume --dry-run validates offline and prints the prepared envelope. Only resume receipts you trust; their hashes are integrity checks, not signatures. Server retention rules apply: an expired key may result in a new charge; do not assume replay is retained indefinitely. Reuse it with the identical effective request after a timeout/interruption; a fresh key represents a new paid forecast. There are no automatic retries. Reserve the output path before submission. If writing a paid artifact fails, the CLI attempts recovery to stdout and exits 8. Save that JSON or retry with the same key (server retention rules apply). Later description/plot failures never rerun inference.`,
+    method: 'POST', path: '/api/v1/forecast',
+    options: { ...input, ...network, resume: string('Recover from a saved submission receipt. Reuses origin, request, and key; mutually exclusive with --input and request overrides.'), receipt: string('New private submission receipt path; default OUTPUT.submission.json or .ephemeris/submissions/<uuid>.json. No receipt is written by --dry-run.'), context: string('Optional local context JSON file or -. Not accepted with frozen snapshots/prepared requests. Only one input may be stdin.'), series: string('Exact series ID from a multi-series inspected snapshot.'), mode: string('route|ensemble|explicit; overrides input mode.'), model: string('Live model name for explicit mode; discover with models list.'), horizon: string('Future sampling steps, integer 1–4096; overrides input. API default 64.'), quantiles: string('Comma-separated unique levels in (0,1), maximum 21, e.g. 0.1,0.5,0.9. Overrides input; omit to retain API/input defaults.'), 'context-len': string('Most recent points per variate, 1–16384. Overrides input; API default 256.'), 'dry-run': boolean('Validate offline and print prepared request/context. No network or charge.'), 'idempotency-key': string('8–128 letters/digits/dot/underscore/colon/hyphen. Default new UUID; retain it for identical retries.') },
+    example: "# Complete synthetic input; replace with actual supplied observations for real work.\ncat > example-request.json <<'JSON'\n{\"mode\":\"route\",\"series\":[{\"values\":[10,12,11],\"freq\":\"D\"}],\"horizon\":2,\"quantiles\":[0.1,0.5,0.9]}\nJSON\ncat > example-context.json <<'JSON'\n{\"series\":[{\"unit\":\"units\",\"measurement\":\"period_total\",\"timezone\":\"UTC\",\"target_description\":\"Synthetic observed sales\",\"timestamps\":[\"2026-01-01\",\"2026-01-02\",\"2026-01-03\"]}]}\nJSON\n# Offline validation; no credentials or charge:\nephemeris forecast run --input example-request.json --context example-context.json --dry-run --output prepared.json\n# Paid submission: requires EPHEMERIS_API_KEY. Receipt is saved before network access.\nephemeris forecast run --input prepared.json --output forecast.json\n# Only after an uncertain result, recover to a NEW file (do not start a fresh request):\n# ephemeris forecast run --resume forecast.json.submission.json --output recovered.json\n# Other modes: add --mode ensemble, or --mode explicit --model NAME from models list.\n# Stdin: cat example-request.json | ephemeris forecast run --input - --dry-run",
+  },
+  'forecast describe': {
+    summary: 'Calculate deterministic interpretation of a saved forecast artifact, offline.',
+    detail: `Requires an ephemeris.forecast v1 artifact saved by forecast run. Select series/variate explicitly when there are multiple. Missing or corrected labels never require paid inference: copy the artifact to a NEW file, edit only its local context.series metadata using caller-supplied facts, leave request/response unchanged, then rerun describe/plot offline. Timestamps must pass the existing grid checks. No dedicated metadata-edit command exists. Returns a Gnomon-aligned overview: scope, result, basis, limitations, references, followups. JSON pointers refer to the INPUT artifact. This is not a Gnomon import or ledger record.
+
+Shows observed count/mean/median/min/max/latest; final forecast median; change against the LAST OBSERVED value; arithmetic mean of per-step medians; and maximum marginal median with tied sampling steps. Percentage change uses 100*(final median-last)/abs(last); zero baseline gives null. A sum of medians is calculated only for caller-declared period_total and is NOT a median or interval of the cumulative total. Missing medians remain missing; no interpolation. Incomplete horizon-wide statistics and non-finite arithmetic return null. Missing units, timezone, and measurement remain unknown. result.billing labels saved millicredit amounts and exact decimal credit conversions; missing values remain null. This is not a current balance check.
+
+Marginal quantiles do not establish calibrated coverage, path probabilities, cumulative intervals, actual peak distributions, causal explanations, trading actions, or inventory actions. Future-channel labels are caller assertions. Absent future inputs mean not supplied, not assumed zero or no events. A forecast jump or narrow/constant band does not by itself establish poor fit or quality; observed outcomes and evaluation are needed. This command makes no inference/LLM call, does not score outcomes, and does not schedule reviews. ${offline}`,
+    options: { ...input, ...selection }, example: `${savedExample}
+ephemeris forecast describe --input example-forecast.json --output description.json
+# For a real saved artifact: ephemeris forecast describe --input forecast.json
+# Multiple results: add --series-index 0 --variate-index 0 (zero-based).`,
+  },
+  'forecast plot': {
+    summary: 'Render PNG or SVG from saved history, median, and quantile bands, offline.',
+    detail: `Requires an ephemeris.forecast v1 artifact with a returned 0.5 quantile. Select series/variate explicitly for multiple results. Choose --output forecast.png for a shareable image, or forecast.svg for scalable output. --format png|svg explicitly selects format; otherwise the filename extension selects it, with SVG as the default for stdout or extensionless files. Conflicting/unsupported extensions reject. PNG stdout is binary and must be piped; it is not written to an interactive terminal. PNG uses a packaged renderer and bundled font, offline. Missing/corrected labels do NOT require a new paid forecast: copy the artifact to a NEW file, edit only its local context.series metadata with caller-supplied facts, keep request/response unchanged, and rerun plot offline. Timestamps must pass the grid checks. No dedicated metadata-edit command exists. No plotting application, browser, or Python installation is required.
+
+Grey is observed history. The default view shows the most recent max(24, 2*horizon) observations, capped by available history; --history N changes that count, --history all shows everything. The chart labels the shown/total counts; the full history is always retained in the artifact. View changes do not change inference or resample observations. Blue is the marginal median; the dashed line marks the forecast boundary. Default bands pair available complementary levels, e.g. q0.1–q0.9, and label nominal mass, not calibrated coverage. Use --lower and --upper together to select one existing band. Missing values break lines; missing/crossed interval points are omitted and counted. Median is never inferred from other quantiles. Available reliable timestamps are used; otherwise the axis uses sampling steps relative to the last observation (0). Named-zone calendar projection across DST can require explicit future_timestamps; no dates are fabricated.
+
+Plots do not show cumulative uncertainty, path probabilities, peak distributions, or business recommendations. Unit/measurement/timezone are shown as supplied or unknown. Plot failure leaves the saved forecast intact; fix arguments or choose a new output path and rerun locally. ${offline}`,
+    options: { ...input, ...selection, format: string('png|svg. Default from --output extension, otherwise svg. PNG stdout is binary; filename must match format.'), history: string('Number of recent observations to display, 1–100000, or all. Default min(available, max(24, 2*horizon)); full history stays saved.'), lower: string('Lower quantile already in saved result, e.g. 0.1. Requires --upper.'), upper: string('Upper quantile already in saved result, e.g. 0.9. Requires --lower.') }, example: `${savedExample}
+ephemeris forecast plot --input example-forecast.json --output forecast.png
+ephemeris forecast plot --input example-forecast.json --output forecast.svg --history all
+# For a real saved artifact: ephemeris forecast plot --input forecast.json --history 48 --lower 0.1 --upper 0.9 --output interval.png`,
+  },
+  'models list': {
+    summary: 'Discover live model capabilities, context/horizon limits, and prices.',
+    detail: 'Authenticated GET /api/v1/models. No forecast or forecast charge. Use before explicit model selection; names/capabilities are not hard-coded. Returns the unmodified catalog JSON, except credential-like fields are redacted. Catalog price_per_kslot_mc means millicredits per 1000 series-slots; billing_context_cap is the maximum billable context. 1000 millicredits = 1 credit. Treat absent capability/price fields as unknown. This does not establish model quality.',
+    method: 'GET', path: '/api/v1/models', options: network, example: 'ephemeris models list --json',
+  },
+  balance: {
+    summary: 'Read available credits and active holds without running a forecast.',
+    detail: 'Authenticated GET /api/v1/balance. No forecast or forecast charge. Fields ending in _mc are millicredit strings; 1000 millicredits = 1 credit ("100" mc is 0.1 credits, not 100 credits). Preserve them to avoid integer precision loss. No billing state is changed.',
+    method: 'GET', path: '/api/v1/balance', options: network, example: 'ephemeris balance --json',
+  },
+  'usage list': {
+    summary: 'Read one page of forecast request history and charges.',
+    detail: 'Authenticated GET /api/v1/usage. No forecast or forecast charge. Use pagination.next_offset for the next page. Rows are in data[]. requestId identifies the gateway request; paracastRequestId identifies the provider request when supplied. estimatedMc and settledMc are exact millicredit strings, not credits; status is the recorded HTTP status when supplied. Preserve IDs and strings; 1000 millicredits = 1 credit. This does not ingest actuals or score forecasts.',
+    method: 'GET', path: '/api/v1/usage', options: { ...network, limit: string('Rows per page, integer 1–200; default 50.'), offset: string('Rows to skip, integer >=0; default 0.') }, example: 'ephemeris usage list --limit 20 --offset 0 --json',
+  },
+  'auth status': {
+    summary: 'Check local credential configuration; optionally verify it with the API.',
+    detail: 'Set EPHEMERIS_API_KEY from your environment/secret manager. No credential arguments or stored credential files. Create a key at https://ephemeris.cascade.industries/dashboard/api-keys. Default reports configured, not verified. --verify performs GET /api/v1/balance; no forecast charge. Keys are never printed. On 401/403 replace/check the key and permissions.',
+    options: { ...network, verify: boolean('Verify key with balance endpoint; default local configuration check only.') }, example: 'ephemeris auth status --verify',
+  },
+  'schema forecast': {
+    summary: 'Print the bundled public forecast request JSON Schema, offline.',
+    detail: `Default --kind request prints the public API request contract. --kind artifact, prepared, data, or submission prints the corresponding local version 1 schema. Each output is standalone JSON Schema with local $defs references. API validation remains authoritative. Local semantic checks additionally enforce shape, covariate alignment, and explicit-mode model selection. Artifacts preserve request/response/context, IDs and billing; prepared records separate the wire request from local context; data records freeze selected observations and diagnostics; submission receipts preserve the exact request and retry key before network access. See forecast run --help for usage. ${offline}`,
+    options: { kind: string('request|artifact|prepared|data|submission. Default request (public wire format); other kinds are local version 1 contracts.') }, example: 'ephemeris schema forecast --output forecast-schema.json\nephemeris schema forecast --kind artifact\nephemeris schema forecast --kind data',
+  },
+};
+export const footer = `Authentication for remote operations: EPHEMERIS_API_KEY environment only.
+Success: JSON (PNG/SVG for plot) on stdout or a new --output file. Errors: JSON Lines on stderr.
+Exit codes: 0 operation success; 2 input/configuration; 3 authentication/permission;
+4 insufficient credits; 5 conflict/rate limit; 6 network/timeout/service;
+7 API/protocol error; 8 file I/O; 130 interrupted.
+401/403: check credentials. 402: add credits. 409/429: inspect API error/Retry-After.
+Timeout: completion may be unknown; use forecast run --resume RECEIPT to reuse the saved request/key. Server retention rules apply.
+Offline commands need no credentials and do not contact the service.
+Missing units, target/business definitions, or future assumptions: ask the user;
+preserve unknowns rather than filling them with plausible guesses. No operation
+establishes forecast accuracy, calibrated coverage, or permission for business actions.
+Missing future inputs mean not supplied, not assumed zero/no events.
+A forecast jump or narrow/constant band alone does not demonstrate good or poor quality.
+Billing _mc values are millicredits: 1000 mc = 1 credit; "100" mc = 0.1 credits.
+Missing labels alone never require new paid inference. Copy a saved artifact to a
+NEW file, correct only caller-supplied local context metadata, keep request/response
+unchanged, and rerun describe/plot offline. No dedicated metadata-edit command exists.`;
+export function help(name) {
+  if (!name) return `Ephemeris ${VERSION} — inspect, forecast, describe, plot\n\nUsage: ephemeris <command> [options]\n\n${Object.entries(commands).map(([n, c]) => `  ${n.padEnd(20)} ${c.summary}`).join('\n')}\n\nDiscover each operation with <command> --help. Start with data inspect --help.
+Workflow: inspect -> forecast run -> forecast describe -> forecast plot.
+Each operation is explicit; only forecast run submits paid inference.
+Options can precede or follow commands. --version prints the version.
+Compatibility: forecast --input ... aliases forecast run; results are now artifacts.
+\n${footer}\n`;
+  const c = commands[name];
+  return `Usage: ephemeris ${name} [options]\n\n${c.summary}\n\n${c.detail}\n\nOptions:\n${Object.entries({ ...c.options, ...common }).map(([n, o]) => `  --${n}${o.short ? `, -${o.short}` : ''}${o.type === 'string' ? ' <value>' : ''}\n      ${o.text}`).join('\n')}\n\nExamples:\n${c.example}\n\n${footer}\n`;
+}

package/src/data.js

@@ -0,0 +1,103 @@
+import { createHash } from 'node:crypto';
+import { extname } from 'node:path';
+import { CliError } from './errors.js';
+import { timeEvidence, checkZone } from './time.js';
+
+export const hash = (value) => createHash('sha256').update(value).digest('hex');
+export const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+export const fail = (message) => { throw new CliError(2, message); };
+
+function delimited(text, delimiter) {
+  const rows = []; let row = [], cell = '', quoted = false, closed = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (quoted) {
+      if (c === '"' && text[i + 1] === '"') { cell += '"'; i++; }
+      else if (c === '"') { quoted = false; closed = true; }
+      else cell += c;
+    } else if (c === '"') {
+      if (cell || closed) fail('Malformed quoted CSV/TSV field.');
+      quoted = true;
+    } else if (c === delimiter || c === '\n' || c === '\r') {
+      row.push(cell); cell = ''; closed = false;
+      if (c !== delimiter) { rows.push(row); row = []; if (c === '\r' && text[i + 1] === '\n') i++; }
+    } else {
+      if (closed) fail('Unexpected characters after a quoted field.');
+      cell += c;
+    }
+  }
+  if (quoted) fail('Unclosed quoted CSV/TSV field.');
+  if (cell || row.length || closed) { row.push(cell); rows.push(row); }
+  if (rows.length < 2) fail('Expected a header and at least one data row.');
+  const names = rows.shift();
+  if (names.some((n) => !n) || new Set(names).size !== names.length) fail('Column names must be non-empty and unique.');
+  return rows.map((r) => {
+    if (r.length !== names.length) fail('Rows must have the same number of fields as the header; blank rows are not silently dropped.');
+    return Object.fromEntries(names.map((name, i) => [name, r[i]]));
+  });
+}
+
+export function metadata(options = {}) {
+  const context = { unit: options.unit ?? null, timezone: options.timezone ?? null, target_description: options['target-description'] ?? null, measurement: options.measurement ?? null };
+  for (const [k, v] of Object.entries(context)) if (v !== null && (typeof v !== 'string' || !v.trim())) fail(`${k} must be a non-empty string when supplied.`);
+  if (context.measurement && !['period_total', 'period_average', 'point_in_time'].includes(context.measurement)) fail('measurement must be period_total, period_average, or point_in_time.');
+  checkZone(context.timezone);
+  return context;
+}
+
+export function inspect(text, options, file = '') {
+  const format = options.format || ({ '.csv': 'csv', '.tsv': 'tsv', '.json': 'json', '.jsonl': 'jsonl', '.ndjson': 'jsonl' })[extname(file).toLowerCase()];
+  if (!['csv', 'tsv', 'json', 'jsonl'].includes(format)) fail('Choose --format csv|tsv|json|jsonl (required for stdin or an unknown extension).');
+  if (!options['value-column']) fail('--value-column is required; choose the observed target explicitly.');
+  const content = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+  let rows;
+  try { rows = format === 'csv' || format === 'tsv' ? delimited(content, format === 'csv' ? ',' : '\t') : format === 'json' ? JSON.parse(content) : content.trimEnd().split(/\r?\n/).map((line) => JSON.parse(line)); }
+  catch (error) { if (error instanceof CliError) throw error; fail('Malformed data file. JSON must be an array of row objects; JSONL needs one row object per line.'); }
+  if (!Array.isArray(rows) || !rows.length || rows.length > 100000 || rows.some((r) => !isObject(r))) fail('Data must contain 1–100000 row objects.');
+  const selected = ['value-column', 'time-column', 'series-column'].filter((k) => options[k]);
+  if (new Set(selected.map((k) => options[k])).size !== selected.length) fail('Select distinct columns for value, time, and series.');
+  for (const key of selected) if (!rows.some((r) => Object.hasOwn(r, options[key]))) fail(`Selected ${key} does not exist. Available columns: ${Object.keys(rows[0]).join(', ')}.`);
+  const context = metadata(options);
+  const groups = new Map();
+  let identifierType;
+  for (const [i, row] of rows.entries()) {
+    const id = options['series-column'] ? row[options['series-column']] : 'series-0';
+    if ((typeof id !== 'string' && typeof id !== 'number') || (typeof id === 'number' && !Number.isFinite(id)) || String(id).trim() === '') fail('Every row must have a non-empty selected series identifier.');
+    if (identifierType && identifierType !== typeof id) fail('Series identifiers must use a consistent type; numeric and string IDs are not silently merged.');
+    identifierType = typeof id;
+    if (!groups.has(String(id))) groups.set(String(id), []);
+    groups.get(String(id)).push({ row: i + 1, value: row[options['value-column']], timestamp: options['time-column'] ? row[options['time-column']] ?? null : null });
+  }
+  const series = [...groups].map(([series_id, entries]) => {
+    let missing = 0, invalid = 0;
+    const missingRows = [], invalidRows = [];
+    const values = entries.map((e) => {
+      const v = e.value;
+      if (v == null || (typeof v === 'string' && /^\s*(?:NA|N\/A|null|nan)?\s*$/i.test(v))) { missing++; missingRows.push(e.row); return null; }
+      const numeric = typeof v === 'number' ? v : (format === 'csv' || format === 'tsv') && typeof v === 'string' && /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(v.trim()) ? Number(v) : NaN;
+      if (!Number.isFinite(numeric)) { invalid++; invalidRows.push(e.row); return null; }
+      return numeric;
+    });
+    const timestamps = options['time-column'] ? entries.map((e) => e.timestamp) : null;
+    const time = timeEvidence(timestamps, options.frequency ?? null, context.timezone);
+    const ready = !missing && !invalid && values.length >= 2 && (timestamps ? time.regular : Boolean(options.frequency));
+    return { series_id, values, timestamps, context: { ...context, frequency: time.effective_frequency }, report: {
+      rows: entries.length, observed_values: values.filter((v) => v !== null).length, zeros: values.filter((v) => v === 0).length,
+      missing_values: missing, invalid_values: invalid, missing_value_rows: missingRows, invalid_value_rows: invalidRows, time,
+      ready_for_forecast: ready, readiness_scope: 'local data shape and grid only; provider suitability not established',
+    } };
+  });
+  return { kind: 'ephemeris.data', schema_version: '1', snapshot_id: hash(JSON.stringify(series)), source: { sha256: hash(text), format, columns: Object.fromEntries(selected.map((k) => [k, options[k]])), row_number_basis: 'one-based data row, excluding header' }, series, repairs: [], history_included: true,
+    limitations: ['Selected input history is included in this snapshot. No sorting, filling, deduplication, or resampling was performed.', 'Observed zeros are measurements, not proof of no underlying demand, a stockout, or a causal explanation.', 'Availability/revision cutoffs were not supplied; this is not a historical leakage check.'] };
+}
+
+export function validateSnapshot(value) {
+  if (value?.kind !== 'ephemeris.data' || value.schema_version !== '1' || !Array.isArray(value.series)) fail('Expected an ephemeris.data version 1 snapshot.');
+  if (value.snapshot_id !== hash(JSON.stringify(value.series))) fail('Snapshot contents changed. Reinspect the original source; the hash is an integrity check, not an authenticity signature.');
+  for (const s of value.series) {
+    if (!isObject(s) || !Array.isArray(s.values) || !isObject(s.context)) fail('Malformed data snapshot.');
+    const time = timeEvidence(s.timestamps, s.context.frequency, s.context.timezone);
+    if (s.values.length < 2 || s.values.some((v) => typeof v !== 'number' || !Number.isFinite(v)) || (s.timestamps !== null && (s.timestamps?.length !== s.values.length || !time.regular)) || (s.timestamps === null && !s.context.frequency)) fail('Snapshot contains missing/invalid values or an incomplete/unsupported time grid. Correct the source explicitly and inspect again.');
+  }
+  return value;
+}