@ggts-sh/spec 0.43.0

package/src/temporal-column.ts

@@ -0,0 +1,323 @@
+/**
+ * Column-level temporal inference and materialization.
+ *
+ * Classifies whole columns (auto parser selection + whole-column validation)
+ * and builds semantic/valid arrays. Value-level engines live in temporal-parse.ts.
+ */
+
+import {
+  DATE_ORDERS,
+  TEMPORAL_PARSER_NAMES,
+  canonicalTemporalParserKey,
+  parseTemporal,
+  temporalParseFailure,
+  type TemporalKind,
+  type TemporalParseOptions,
+  type TemporalParserName,
+  type TemporalParserSpec,
+  type TemporalPrecision,
+} from "./temporal-parse.js";
+
+export interface TemporalFailure {
+  index: number;
+  value: string | number | boolean | null;
+  reason: string;
+}
+
+export interface TemporalDecision {
+  status: "temporal" | "nominal" | "ambiguous" | "invalid";
+  parser: string | null;
+  parserKey: string;
+  kind: TemporalKind | null;
+  precision: TemporalPrecision | null;
+  evidence: readonly (string | number | boolean | null)[];
+  nonNullCount: number;
+  validatedCount: number;
+  failedCount: number;
+  candidates: readonly string[];
+  failures?: readonly TemporalFailure[];
+}
+
+export interface ParsedTemporalColumn {
+  decision: TemporalDecision;
+  semantic: Float64Array;
+  valid: Uint8Array;
+}
+
+const PRECISION_RANK: Readonly<Record<TemporalPrecision, number>> = {
+  year: 0,
+  quarter: 1,
+  month: 2,
+  date: 3,
+  minute: 4,
+  second: 5,
+  millisecond: 6,
+};
+
+function finestPrecision(
+  current: TemporalPrecision | null,
+  candidate: TemporalPrecision,
+): TemporalPrecision {
+  return current === null || PRECISION_RANK[candidate] > PRECISION_RANK[current]
+    ? candidate
+    : current;
+}
+
+function evidenceValue(value: unknown): string | number | boolean | null {
+  if (value instanceof Date)
+    return Number.isFinite(value.getTime()) ? value.toISOString() : "Invalid Date";
+  if (
+    typeof value === "string" ||
+    typeof value === "number" ||
+    typeof value === "boolean" ||
+    value === null
+  ) {
+    return value;
+  }
+  if (typeof value === "bigint") return value.toString();
+  return JSON.stringify(value) ?? "unsupported value";
+}
+
+/**
+ * One full-column pass: non-null count, full-column number/boolean detection
+ * (not sample-relative), and a representative sample of at most 64 non-null
+ * values (all when ≤64; otherwise first 32 + last 32). Avoids allocating an
+ * O(n) non-null array just to take a bounded sample.
+ */
+function analyzeNonNull(values: readonly unknown[]): {
+  sample: unknown[];
+  nonNullCount: number;
+  sawNumberOrBoolean: boolean;
+} {
+  let nonNullCount = 0;
+  let sawNumberOrBoolean = false;
+  const head: unknown[] = [];
+  const ring: unknown[] = Array.from({ length: 32 });
+  let ringWrite = 0;
+  let ringLen = 0;
+
+  for (const value of values) {
+    if (value === null || value === undefined) continue;
+    nonNullCount++;
+    if (typeof value === "number" || typeof value === "boolean") sawNumberOrBoolean = true;
+    if (head.length < 64) head.push(value);
+    ring[ringWrite] = value;
+    ringWrite = (ringWrite + 1) % 32;
+    if (ringLen < 32) ringLen++;
+  }
+
+  if (nonNullCount <= 64) {
+    return { sample: head, nonNullCount, sawNumberOrBoolean };
+  }
+
+  const first = head.slice(0, 32);
+  const last: unknown[] = [];
+  // When full, ringWrite points at the oldest slot.
+  for (let i = 0; i < 32; i++) last.push(ring[(ringWrite + i) % 32]);
+  return { sample: [...first, ...last], nonNullCount, sawNumberOrBoolean };
+}
+
+const AUTO_ORDERED_PARSERS = TEMPORAL_PARSER_NAMES.filter((parser): parser is TemporalParserName =>
+  DATE_ORDERS.has(parser.split("_")[0]!),
+);
+
+function candidateParsers(
+  sample: readonly unknown[],
+  options: TemporalParseOptions,
+): TemporalParserName[] {
+  const strings = sample.filter((value): value is string => typeof value === "string");
+  const nonDates = sample.filter((value) => !(value instanceof Date));
+  const mixedWithDates = strings.length > 0 && sample.some((value) => value instanceof Date);
+  if (strings.length === 0 && sample.every((value) => value instanceof Date)) return [];
+  if (strings.length !== nonDates.length) return [];
+  if (strings.every((value) => parseTemporal(value, "iso", options).ok)) return ["iso"];
+  // Native Date values are instants. Mixing them with lower-precision year,
+  // month, quarter, or ordered-date strings has no coherent parser identity.
+  if (mixedWithDates) return [];
+  for (const parser of ["year", "ym", "my", "yq"] as const) {
+    if (strings.every((value) => parseTemporal(value, parser, options).ok)) return [parser];
+  }
+  // Explicit ordered parsers may accept compact years, but automatic
+  // inference never assigns meaning to a two-digit year.
+  if (strings.some((value) => !/(?:^|[-/.])\d{4}(?:[-/.]|[T ]|$)/.test(value))) return [];
+  return AUTO_ORDERED_PARSERS.filter((parser) =>
+    strings.every((value) => {
+      if (value.includes("-") && /^\d{4}-\d{2}-\d{2}/.test(value)) return false;
+      return parseTemporal(value, parser, options).ok;
+    }),
+  );
+}
+
+function nominalDecision(
+  status: TemporalDecision["status"],
+  values: readonly unknown[],
+  candidates: readonly string[] = [],
+  analyzed?: ReturnType<typeof analyzeNonNull>,
+): TemporalDecision {
+  const { sample, nonNullCount } = analyzed ?? analyzeNonNull(values);
+  return {
+    status,
+    parser: null,
+    parserKey: `auto:${status}`,
+    kind: null,
+    precision: null,
+    evidence: sample.slice(0, 8).map((value) => evidenceValue(value)),
+    nonNullCount,
+    validatedCount: 0,
+    failedCount: 0,
+    candidates,
+  };
+}
+
+function inferTemporalColumnInternal(
+  values: readonly unknown[],
+  options: TemporalParseOptions = {},
+  onSuccess?: (index: number, epochMs: number) => void,
+): TemporalDecision {
+  const analyzed = analyzeNonNull(values);
+  if (analyzed.nonNullCount === 0) return nominalDecision("nominal", values, [], analyzed);
+  // Full-column fact (not sample-relative): any number/boolean forces nominal.
+  if (analyzed.sawNumberOrBoolean) return nominalDecision("nominal", values, [], analyzed);
+  const { sample, nonNullCount } = analyzed;
+  if (sample.some((value) => !(value instanceof Date) && typeof value !== "string")) {
+    return nominalDecision("nominal", values, [], analyzed);
+  }
+  const candidates = candidateParsers(sample, options);
+  const allDates = sample.every((value) => value instanceof Date);
+  if (!allDates && candidates.length === 0) return nominalDecision("nominal", values, [], analyzed);
+  if (candidates.length > 1) return nominalDecision("ambiguous", values, candidates, analyzed);
+
+  const parser = allDates ? null : candidates[0]!;
+  const scan = scanTemporalValues(values, parser, options, onSuccess);
+  const failedCount = nonNullCount - scan.validatedCount;
+  if (failedCount > 0) {
+    return {
+      ...nominalDecision("invalid", values, parser === null ? ["native-date"] : [parser], analyzed),
+      parser,
+      parserKey: `auto:${parser ?? "native-date"}:invalid`,
+      validatedCount: scan.validatedCount,
+      failedCount,
+      failures: scan.failures,
+    };
+  }
+  return {
+    status: "temporal",
+    parser: parser ?? "native-date",
+    parserKey: `auto:${parser ?? "native-date"}`,
+    kind: scan.kind ?? "datetime",
+    precision: scan.precision ?? "millisecond",
+    evidence: sample.slice(0, 8).map((value) => evidenceValue(value)),
+    nonNullCount,
+    validatedCount: scan.validatedCount,
+    failedCount: 0,
+    candidates: parser === null ? ["native-date"] : [parser],
+  };
+}
+
+function scanTemporalValues(
+  values: readonly unknown[],
+  parser: TemporalParserName | null,
+  options: TemporalParseOptions,
+  onSuccess?: (index: number, epochMs: number) => void,
+): {
+  validatedCount: number;
+  failures: TemporalFailure[];
+  kind: TemporalKind | null;
+  precision: TemporalPrecision | null;
+} {
+  let validatedCount = 0;
+  const failures: TemporalFailure[] = [];
+  let kind: TemporalKind | null = null;
+  let precision: TemporalPrecision | null = null;
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index];
+    if (value === null || value === undefined) continue;
+    const parsed =
+      value instanceof Date
+        ? parseTemporal(value, "iso", options)
+        : parser === null
+          ? temporalParseFailure("mixed non-Date value in native Date column")
+          : parseTemporal(value, parser, options);
+    if (!parsed.ok) {
+      if (failures.length < 5)
+        failures.push({ index, value: evidenceValue(value), reason: parsed.reason });
+      continue;
+    }
+    validatedCount++;
+    onSuccess?.(index, parsed.epochMs);
+    kind = kind === "datetime" || parsed.kind === "datetime" ? "datetime" : "date";
+    precision = finestPrecision(precision, parsed.precision);
+  }
+  return { validatedCount, failures, kind, precision };
+}
+
+export function inferTemporalColumn(
+  values: readonly unknown[],
+  options: TemporalParseOptions = {},
+): TemporalDecision {
+  return inferTemporalColumnInternal(values, options);
+}
+
+export function parseTemporalColumn(
+  values: readonly unknown[],
+  parser: TemporalParserSpec | "auto" = "auto",
+  options: TemporalParseOptions = {},
+): ParsedTemporalColumn {
+  const semantic = new Float64Array(values.length);
+  semantic.fill(Number.NaN);
+  const valid = new Uint8Array(values.length);
+  if (parser === "auto") {
+    const decision = inferTemporalColumnInternal(values, options, (index, epochMs) => {
+      semantic[index] = epochMs;
+      valid[index] = 1;
+    });
+    if (decision.status !== "temporal") {
+      semantic.fill(Number.NaN);
+      valid.fill(0);
+    }
+    return { decision, semantic, valid };
+  }
+
+  let validatedCount = 0;
+  let nonNullCount = 0;
+  let kind: TemporalKind | null = null;
+  let precision: TemporalPrecision | null = null;
+  const failures: TemporalFailure[] = [];
+  const evidence: (string | number | boolean | null)[] = [];
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index];
+    if (value === null || value === undefined) continue;
+    nonNullCount++;
+    if (evidence.length < 8) evidence.push(evidenceValue(value));
+    const result = parseTemporal(value, parser, options);
+    if (!result.ok) {
+      if (failures.length < 5)
+        failures.push({ index, value: evidenceValue(value), reason: result.reason });
+      continue;
+    }
+    semantic[index] = result.epochMs;
+    valid[index] = 1;
+    validatedCount++;
+    kind = kind === "datetime" || result.kind === "datetime" ? "datetime" : "date";
+    precision = finestPrecision(precision, result.precision);
+  }
+  const failedCount = nonNullCount - validatedCount;
+  const parserKey = canonicalTemporalParserKey(parser);
+  return {
+    semantic,
+    valid,
+    decision: {
+      status: failedCount === 0 ? "temporal" : "invalid",
+      parser: typeof parser === "string" ? parser : parserKey,
+      parserKey,
+      kind: kind ?? null,
+      precision: precision ?? null,
+      evidence,
+      nonNullCount,
+      validatedCount,
+      failedCount,
+      candidates: [parserKey],
+      ...(failures.length > 0 && { failures }),
+    },
+  };
+}

package/src/temporal-guides.ts

@@ -0,0 +1,32 @@
+/**
+ * Temporal guides facade — portable intervals/labels and tick generation.
+ *
+ * Implementation:
+ *  - temporal-interval.ts — units, parse, label tokens, locale checks
+ *  - temporal-ticks.ts — calendar-aligned interval ticks
+ */
+
+export {
+  MAX_TEMPORAL_CANDIDATES,
+  MAX_TEMPORAL_MAJOR_TICKS,
+  MAX_TEMPORAL_MINOR_TICKS,
+  MIN_TEMPORAL_LABEL_GAP_PX,
+  parseTemporalInterval,
+  TEMPORAL_INTERVAL_UNITS,
+  TEMPORAL_LABEL_TOKENS,
+  TEMPORAL_WEEKDAYS,
+  TemporalIntervalError,
+  temporalLabelConfigurationError,
+  temporalLocaleConfigurationError,
+  type TemporalInterval,
+  type TemporalIntervalSpec,
+  type TemporalIntervalUnit,
+  type TemporalWeekStart,
+} from "./temporal-interval.js";
+export {
+  TemporalIntervalSpecSchema,
+  TemporalLabelSpecSchema,
+  TemporalWeekStartSchema,
+} from "./temporal-interval-schema.js";
+
+export { temporalIntervalTicks } from "./temporal-ticks.js";

package/src/temporal-interval-schema.ts

@@ -0,0 +1,40 @@
+/**
+ * TypeBox schemas for temporal intervals and labels (schema graph / validate only).
+ * Runtime parse + label checks live in temporal-interval.ts without typebox.
+ */
+import Type, { type TLiteral } from "typebox";
+
+import {
+  TEMPORAL_LABEL_TOKENS,
+  TEMPORAL_WEEKDAYS,
+  type TemporalWeekStart,
+} from "./temporal-interval.js";
+
+const WEEKDAY_SCHEMAS = TEMPORAL_WEEKDAYS.map((weekday) => Type.Literal(weekday)) as unknown as [
+  TLiteral<TemporalWeekStart>,
+  ...TLiteral<TemporalWeekStart>[],
+];
+
+const TEMPORAL_INTERVAL_STEP_PATTERN = "(?:[1-9][0-9]{0,5}|1000000)";
+
+export const TemporalIntervalSpecSchema = Type.String({
+  minLength: 1,
+  maxLength: 128,
+  pattern: `^[ ]*${TEMPORAL_INTERVAL_STEP_PATTERN}[ ]+(?:millisecond|second|minute|hour|day|week|month|quarter|year)s?[ ]*$`,
+  description:
+    'A positive integer calendar interval such as "2 weeks", "3 months", or "10 years". Canonical units are millisecond, second, minute, hour, day, week, month, quarter, and year.',
+});
+
+export const TemporalWeekStartSchema = Type.Union(WEEKDAY_SCHEMAS, {
+  description: 'Week boundary used by temporal interval breaks. Default "monday".',
+});
+
+const TEMPORAL_LABEL_PATTERN = `^(?:[^%]|%(?:${TEMPORAL_LABEL_TOKENS.join("|")}))+$`;
+
+export const TemporalLabelSpecSchema = Type.String({
+  minLength: 1,
+  maxLength: 128,
+  pattern: TEMPORAL_LABEL_PATTERN,
+  description:
+    "Strict temporal label format. Supported tokens: %Y %y %m %b %B %d %e %a %A %H %I %M %S %L %p %q %z %Z %%.",
+});

package/src/temporal-interval.ts

@@ -0,0 +1,151 @@
+/**
+ * Portable temporal interval grammar, label token contract, and locale checks.
+ * Tick generation lives in temporal-ticks.ts; facade re-exports in temporal-guides.ts.
+ */
+
+import type { TemporalScaleKind } from "./temporal-parse-core.js";
+
+export const TEMPORAL_INTERVAL_UNITS = [
+  "millisecond",
+  "second",
+  "minute",
+  "hour",
+  "day",
+  "week",
+  "month",
+  "quarter",
+  "year",
+] as const;
+export type TemporalIntervalUnit = (typeof TEMPORAL_INTERVAL_UNITS)[number];
+
+export const TEMPORAL_WEEKDAYS = [
+  "monday",
+  "tuesday",
+  "wednesday",
+  "thursday",
+  "friday",
+  "saturday",
+  "sunday",
+] as const;
+export type TemporalWeekStart = (typeof TEMPORAL_WEEKDAYS)[number];
+
+const TEMPORAL_INTERVAL_STEP_PATTERN = "(?:[1-9][0-9]{0,5}|1000000)";
+
+/** Portable interval string (schema-validated by TypeBox on the agent path). */
+export type TemporalIntervalSpec = string;
+
+export interface TemporalInterval {
+  unit: TemporalIntervalUnit;
+  step: number;
+  key: string;
+}
+
+export const MAX_TEMPORAL_CANDIDATES = 128;
+export const MAX_TEMPORAL_MAJOR_TICKS = 64;
+export const MAX_TEMPORAL_MINOR_TICKS = 256;
+export const MIN_TEMPORAL_LABEL_GAP_PX = 6;
+
+export class TemporalIntervalError extends Error {
+  readonly value: string;
+
+  constructor(value: string, reason: string) {
+    super(`Invalid temporal interval ${JSON.stringify(value)}: ${reason}.`);
+    this.name = "TemporalIntervalError";
+    this.value = value;
+  }
+}
+
+const INTERVAL_RE = new RegExp(
+  `^(${TEMPORAL_INTERVAL_STEP_PATTERN}) +(millisecond|second|minute|hour|day|week|month|quarter|year)(s?)$`,
+);
+
+export function parseTemporalInterval(value: string): TemporalInterval;
+export function parseTemporalInterval(value: unknown): TemporalInterval {
+  if (typeof value !== "string" || value.length > 128) {
+    throw new TemporalIntervalError(String(value), "expected a string of at most 128 characters");
+  }
+  const match = INTERVAL_RE.exec(value.replaceAll(/^ +| +$/g, ""));
+  if (match === null) {
+    throw new TemporalIntervalError(
+      value,
+      'expected "<positive integer> <unit>" using a canonical calendar unit',
+    );
+  }
+  const step = Number(match[1]);
+  if (!Number.isSafeInteger(step) || step < 1 || step > 1_000_000) {
+    throw new TemporalIntervalError(value, "step must be an integer from 1 through 1,000,000");
+  }
+  const unit = match[2] as TemporalIntervalUnit;
+  return { unit, step, key: `${step} ${unit}${step === 1 ? "" : "s"}` };
+}
+
+export const TEMPORAL_LABEL_TOKENS = [
+  "Y",
+  "y",
+  "m",
+  "b",
+  "B",
+  "d",
+  "e",
+  "a",
+  "A",
+  "H",
+  "I",
+  "M",
+  "S",
+  "L",
+  "p",
+  "q",
+  "z",
+  "Z",
+  "%",
+] as const;
+const LABEL_TOKEN_SET = new Set<string>(TEMPORAL_LABEL_TOKENS);
+/**
+ * Tokens a month-day axis can fill truthfully: those the month and the day
+ * determine. A year is absent by construction; the clock and zone would print
+ * the same midnight-UTC zeros for every tick; and the weekday belongs to the
+ * reference year, not to the observation — 1 April fell on different weekdays
+ * in 812 and 2001, so printing one would invent a fact.
+ */
+const MONTH_DAY_LABEL_TOKENS = new Set(["m", "b", "B", "d", "e", "q", "%"]);
+
+export function temporalLabelConfigurationError(
+  pattern: string,
+  kind?: TemporalScaleKind,
+): string | null {
+  if (pattern.length === 0 || pattern.length > 128) {
+    return "dateLabels must contain 1 through 128 characters";
+  }
+  for (let index = 0; index < pattern.length; index++) {
+    if (pattern[index] !== "%") continue;
+    const token = pattern[++index];
+    if (token === undefined || !LABEL_TOKEN_SET.has(token)) {
+      return `unsupported dateLabels token %${token ?? ""}`;
+    }
+    if (kind === "monthDay" && !MONTH_DAY_LABEL_TOKENS.has(token)) {
+      return `dateLabels token %${token} has no meaning on a monthDay axis, which knows only a month and a day; use one of %m %b %B %d %e %q`;
+    }
+  }
+  return null;
+}
+
+export function temporalLocaleConfigurationError(locale: string): string | null {
+  if (locale.length === 0 || locale.length > 128) {
+    return "locale must contain 1 through 128 characters";
+  }
+  try {
+    const canonical = Intl.getCanonicalLocales(locale);
+    if (canonical.length !== 1) return `invalid or unsupported locale ${JSON.stringify(locale)}`;
+    const supported = Intl.DateTimeFormat.supportedLocalesOf(canonical, {
+      localeMatcher: "lookup",
+    });
+    if (supported.length !== 1) {
+      return `invalid or unsupported locale ${JSON.stringify(locale)}`;
+    }
+    new Intl.DateTimeFormat(canonical[0], { timeZone: "UTC", year: "numeric" }).format(0);
+    return null;
+  } catch {
+    return `invalid or unsupported locale ${JSON.stringify(locale)}`;
+  }
+}