@ggts-sh/spec 0.43.0

package/src/validate-data-checks.ts

@@ -0,0 +1,157 @@
+/**
+ * Tier-2 data-aware orchestrator — resolve evidence, walk layers, then scale/type
+ * compatibility (style → position → color diagnostic order).
+ *
+ * Implementation:
+ *  - validate-data-checks-layer.ts — geom/stat rules + field walk + channel collection
+ *  - validate-data-checks-temporal.ts — shared temporalDecisionForField memoization
+ *  - validate-data-checks-position.ts — pre-evidence temporal axis config + x/y scale types
+ *  - validate-data-checks-color.ts — color/fill scale types + manual domain/range
+ *  - validate-data-checks-color-temporal.ts — temporal censor recovery lattice
+ *  - validate-data-checks-style.ts — shape/linetype + size/linewidth/alpha (finite + numeric modules)
+ *
+ * Style and color scale checks take the same per-use `evidenceForUse` path as
+ * position (#609 / #844): multi-table layers that share a field name keep their
+ * own type evidence. The last-wins union `fields` map remains a fallback only.
+ *
+ * Evidence is one `resolveLayerFieldEvidence` pass (plot + per-layer tables).
+ * validate() may pre-resolve and pass the result so lint shares the same pass.
+ */
+import type { SpecError } from "./errors.js";
+import type { Aes, ChannelName } from "./schema.js";
+import type { ValidateLimits, ValidateOptions } from "./validate-data.js";
+import {
+  resolveLayerFieldEvidence,
+  type FieldEvidenceMap,
+  type ResolveLayerFieldEvidenceResult,
+} from "./validate-data-evidence.js";
+import { checkColorScaleDataCompatibility } from "./validate-data-checks-color.js";
+import { collectLayerDataChecks, STAT_COLUMNS } from "./validate-data-checks-layer.js";
+import {
+  checkPositionScaleDataCompatibility,
+  scaleRequestsTime,
+  validateTemporalAxisConfiguration,
+} from "./validate-data-checks-position.js";
+import {
+  checkFiniteStyleScaleDataCompatibility,
+  checkNumericStyleScaleDataCompatibility,
+} from "./validate-data-checks-style.js";
+import type { TemporalDecisionCache } from "./validate-data-checks-temporal.js";
+
+export { STAT_COLUMNS };
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export function dataChecks(
+  spec: Record<string, unknown>,
+  options: ValidateOptions,
+  limits: ValidateLimits,
+  /**
+   * Pre-resolved layer evidence from validate() so the pivot/type pass runs
+   * once and can be shared with lintSpec.
+   */
+  preResolvedLayer?: ResolveLayerFieldEvidenceResult,
+): SpecError[] {
+  const errors: SpecError[] = [];
+  // One cache per dataChecks call — shared by position, color, and style checkers.
+  // Nested by FieldEvidenceEntry so same-named fields on different datasets stay independent (#1339).
+  const temporalDecisionCache: TemporalDecisionCache = new Map();
+  const scales = isRecord(spec["scales"]) ? spec["scales"] : undefined;
+
+  // Pre-evidence: temporal axis configuration (errors even without data/profile).
+  const temporalConfig = validateTemporalAxisConfiguration(scales);
+  errors.push(...temporalConfig.errors);
+  const { invalidTemporalAxes } = temporalConfig;
+
+  // One pass over plot + layer tables (#589 multi-table evidence).
+  const layerResolved = preResolvedLayer ?? resolveLayerFieldEvidence(spec, options, limits);
+  if (layerResolved.status === "errors") return [...errors, ...layerResolved.errors];
+  if (layerResolved.status === "none") return errors;
+
+  const plotFields: FieldEvidenceMap | null = layerResolved.plot;
+  const layerMaps = layerResolved.layers;
+
+  const plotAes = isRecord(spec["aes"]) ? (spec["aes"] as Aes) : undefined;
+  const layers = Array.isArray(spec["layers"]) ? (spec["layers"] as unknown[]) : [];
+  const scaleRequestsTimeForChannel = (channel: ChannelName): boolean => {
+    const axis =
+      channel === "x" || channel === "xmin" || channel === "xmax" || channel === "xend"
+        ? "x"
+        : channel === "y" || channel === "ymin" || channel === "ymax" || channel === "yend"
+          ? "y"
+          : null;
+    return axis !== null && scaleRequestsTime(scales, axis);
+  };
+
+  const walk = collectLayerDataChecks({
+    layers,
+    plotAes,
+    plotFields,
+    layerMaps,
+    scaleRequestsTime: scaleRequestsTimeForChannel,
+  });
+  errors.push(...walk.errors);
+
+  // --- scale/type compatibility (order preserved for diagnostics) ------------
+  // Union layer evidence as a fallback for non-layer-scoped lookups. Position,
+  // style, and color scale checks prefer per-layer evidence via evidenceForUse
+  // so same field names on different tables stay independent (#609 / #844).
+  const fields: FieldEvidenceMap = new Map(plotFields ?? undefined);
+  for (const layerMap of layerMaps) {
+    if (layerMap === null) continue;
+    for (const [name, entry] of layerMap) fields.set(name, entry);
+  }
+  const evidenceForUse = (use: { field: string; path: string }) => {
+    const match = /^\/layers\/(\d+)\//.exec(use.path);
+    if (match !== null) {
+      const layerMap = layerMaps[Number(match[1])];
+      if (layerMap !== null && layerMap !== undefined) {
+        const hit = layerMap.get(use.field);
+        if (hit !== undefined) return hit;
+      }
+      // Layer with no override inherits plot evidence.
+      if (plotFields !== null) {
+        const hit = plotFields.get(use.field);
+        if (hit !== undefined) return hit;
+      }
+    }
+    return fields.get(use.field);
+  };
+  // Diagnostic order: finite style → numeric style → position → color.
+  errors.push(
+    ...checkFiniteStyleScaleDataCompatibility({
+      scales,
+      fields,
+      evidenceForUse,
+      finiteStyleFields: walk.finiteStyleFields,
+    }),
+    ...checkNumericStyleScaleDataCompatibility({
+      scales,
+      fields,
+      evidenceForUse,
+      numericStyleFields: walk.numericStyleFields,
+      numericStyleScaledConstants: walk.numericStyleScaledConstants,
+      temporalDecisionCache,
+    }),
+    ...checkPositionScaleDataCompatibility({
+      scales,
+      fields,
+      evidenceForUse,
+      axisFields: walk.axisFields,
+      invalidTemporalAxes,
+      temporalDecisionCache,
+    }),
+    ...checkColorScaleDataCompatibility({
+      scales,
+      fields,
+      evidenceForUse,
+      colorFields: walk.colorFields,
+      colorScaledConstants: walk.colorScaledConstants,
+      temporalDecisionCache,
+    }),
+  );
+
+  return errors;
+}

package/src/validate-data-evidence.ts

@@ -0,0 +1,419 @@
+/**
+ * Field-evidence construction for tier-2 validation and lint.
+ *
+ * `resolveLayerFieldEvidence` builds plot + per-layer maps in one pass
+ * (pivot + type inference, under input limits). validate() runs that once and
+ * shares the result with dataChecks and lintSpec so large inline data is not
+ * scanned twice. Standalone lintSpec / resolveFieldEvidence still use the
+ * plot-only path.
+ */
+import type { SpecError } from "./errors.js";
+import type { Aes, CellValue, ChannelName } from "./schema.js";
+import { inferTemporalColumn, type TemporalDecision } from "./temporal-column.js";
+import type { ProfileFieldType, ValidateLimits, ValidateOptions } from "./validate-data.js";
+
+// ---------------------------------------------------------------------------
+// Field evidence types
+// ---------------------------------------------------------------------------
+
+/**
+ * One field's type evidence for tier-2 checks and lint. Built once per
+ * validate() when both dataChecks and lintSpec run, so large inline data is
+ * not pivoted/type-scanned twice.
+ */
+export interface FieldEvidenceEntry {
+  type: ProfileFieldType | null;
+  /** True when the column exists but has only null values (inline data only). */
+  allNull: boolean;
+  /** Raw column values (inline data only; null for profile-backed fields). */
+  values: readonly CellValue[] | null;
+  /** Shared value-driven temporal decision (inline data only). */
+  temporal: TemporalDecision | null;
+}
+
+export type FieldEvidenceMap = Map<string, FieldEvidenceEntry>;
+
+/** Result of resolving profile/inline data into a field evidence map. */
+export type ResolveFieldEvidenceResult =
+  | { status: "ok"; fields: FieldEvidenceMap }
+  | { status: "none" }
+  | { status: "errors"; errors: SpecError[] };
+
+/** Plot + per-layer field evidence from one pass over inline tables / profile. */
+export type ResolveLayerFieldEvidenceResult =
+  /**
+   * `layers[i]` may be the same object as `plot` or as another layer's entry
+   * when those layers read one dataset. Treat every map as read-only; copy
+   * before writing.
+   */
+  | { status: "ok"; plot: FieldEvidenceMap | null; layers: Array<FieldEvidenceMap | null> }
+  | { status: "none" }
+  | { status: "errors"; errors: SpecError[] };
+
+// ---------------------------------------------------------------------------
+// Channel helper (shared by structure checks, data checks, and lint)
+// ---------------------------------------------------------------------------
+
+/** The channel a layer effectively sees (layer wins; null unsets). */
+export function effectiveChannel(
+  plotAes: Aes | undefined,
+  layerAes: Aes | undefined,
+  channel: ChannelName,
+): Exclude<Aes[ChannelName], null | undefined> | undefined {
+  const own = layerAes?.[channel];
+  if (own === null) return undefined;
+  const chosen = own ?? plotAes?.[channel];
+  return chosen ?? undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Type inference + profile / inline resolution
+// ---------------------------------------------------------------------------
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+const PROFILE_TYPES: ReadonlySet<string> = new Set([
+  "quantitative",
+  "temporal",
+  "ordinal",
+  "nominal",
+]);
+
+function inferProfileType(column: readonly CellValue[]): {
+  type: ProfileFieldType | null;
+  temporal: TemporalDecision;
+} {
+  const temporal = inferTemporalColumn(column);
+  if (temporal.status === "temporal") return { type: "temporal", temporal };
+  let sawNumber = false;
+  let sawValue = false;
+  for (const value of column) {
+    if (value === null) continue;
+    sawValue = true;
+    if (typeof value === "boolean" || typeof value === "string") {
+      return { type: "nominal", temporal };
+    }
+    if (typeof value === "number") sawNumber = true;
+  }
+  return { type: sawNumber ? "quantitative" : sawValue ? "nominal" : null, temporal };
+}
+
+function badProfile(message: string): SpecError[] {
+  return [
+    {
+      code: "invalid-data-profile",
+      path: "",
+      message: `Invalid DataProfile: ${message}`,
+      fix: {
+        description:
+          'Provide { fields: [{ name, type: "quantitative"|"temporal"|"ordinal"|"nominal" }], rowCount? }.',
+        example: { fields: [{ name: "displ", type: "quantitative" }], rowCount: 234 },
+      },
+    },
+  ];
+}
+
+function profileErrors(profile: unknown): SpecError[] {
+  if (!isRecord(profile)) return badProfile("expected an object.");
+  if (!Array.isArray(profile["fields"])) return badProfile('"fields" must be an array.');
+  for (const field of profile["fields"] as unknown[]) {
+    if (!isRecord(field) || typeof field["name"] !== "string") {
+      return badProfile('every field needs a string "name".');
+    }
+    if (typeof field["type"] !== "string" || !PROFILE_TYPES.has(field["type"])) {
+      return badProfile(
+        `field "${field["name"]}" has type ${JSON.stringify(field["type"])}; allowed: quantitative, temporal, ordinal, nominal.`,
+      );
+    }
+  }
+  if (profile["rowCount"] !== undefined && typeof profile["rowCount"] !== "number") {
+    return badProfile('"rowCount" must be a number when present.');
+  }
+  return [];
+}
+
+/**
+ * Resolve inline columns from a data ref against optional named datasets.
+ * Named refs that are not present in datasets return null (runtime-only data).
+ */
+function columnsFromDataRef(
+  data: unknown,
+  datasets: unknown,
+): Record<string, readonly CellValue[]> | null {
+  let ref = data;
+  if (isRecord(ref) && typeof ref["name"] === "string") {
+    ref = isRecord(datasets) ? datasets[ref["name"]] : undefined;
+  }
+  if (!isRecord(ref)) return null;
+  if (Array.isArray(ref["values"])) {
+    const rows = ref["values"] as Record<string, CellValue>[];
+    const columns: Record<string, CellValue[]> = {};
+    for (const row of rows) {
+      if (!isRecord(row)) continue;
+      for (const key of Object.keys(row)) columns[key] ??= [];
+    }
+    for (const key of Object.keys(columns)) {
+      const column = columns[key]!;
+      for (const row of rows) column.push(isRecord(row) ? (row[key] ?? null) : null);
+    }
+    return columns;
+  }
+  if (isRecord(ref["columns"])) {
+    return ref["columns"] as Record<string, readonly CellValue[]>;
+  }
+  return null;
+}
+
+/** Resolve the spec's plot-level inline columns ({values}, {columns}, or named). */
+function inlineColumns(spec: Record<string, unknown>): Record<string, readonly CellValue[]> | null {
+  return columnsFromDataRef(spec["data"], spec["datasets"]);
+}
+
+function evidenceFromColumns(columns: Record<string, readonly CellValue[]>): FieldEvidenceMap {
+  const fields: FieldEvidenceMap = new Map();
+  for (const name of Object.keys(columns)) {
+    const column = columns[name]!;
+    const inferred = inferProfileType(column);
+    fields.set(name, {
+      type: inferred.type,
+      allNull: column.length > 0 && inferred.type === null,
+      values: column,
+      temporal: inferred.temporal,
+    });
+  }
+  return fields;
+}
+
+/**
+ * Per-layer field evidence (#589). Each layer inherits plot-level evidence
+ * unless it supplies its own inline/named-inline data.
+ * Layers with only unresolved named (runtime) data get `null` (skip type checks).
+ */
+export function resolveLayerFieldEvidence(
+  spec: Record<string, unknown>,
+  options: ValidateOptions,
+  limits: ValidateLimits,
+): ResolveLayerFieldEvidenceResult {
+  if (options.profile !== undefined) {
+    return evidenceFromProfile(options.profile, spec);
+  }
+
+  const datasets = spec["datasets"];
+  const plotColumns = inlineColumns(spec);
+  let totalRows = 0;
+  let totalBytes = 0;
+  const countedTables = new Set<string>();
+  const countTable = (key: string, columns: Record<string, readonly CellValue[]>) => {
+    if (countedTables.has(key)) return;
+    countedTables.add(key);
+    const names = Object.keys(columns);
+    const rowCount = names.length === 0 ? 0 : (columns[names[0]!]?.length ?? 0);
+    totalRows += rowCount;
+    totalBytes += estimateBytes(columns, rowCount);
+  };
+  if (plotColumns !== null) {
+    // Prefer name: key so plot-level { name } matching a layer named ref is not
+    // double-counted toward maxRows (same embedded/named dataset once).
+    const plotData = spec["data"];
+    const plotKey =
+      isRecord(plotData) && typeof plotData["name"] === "string"
+        ? `name:${plotData["name"]}`
+        : "__plot__";
+    countTable(plotKey, plotColumns);
+  }
+
+  const layers = Array.isArray(spec["layers"]) ? (spec["layers"] as unknown[]) : [];
+  // Several layers commonly name one dataset. Pivoting {values} rows into
+  // columns is O(rows x columns), so resolve each name once rather than once
+  // per reference. Inline data keeps its own table: equal content is not the
+  // same table.
+  const columnsByName = new Map<string, Record<string, readonly CellValue[]>>();
+  const plotData = spec["data"];
+  const plotName =
+    isRecord(plotData) && typeof plotData["name"] === "string" ? plotData["name"] : null;
+  // The plot's own table seeds it, so a layer naming the plot's dataset reuses
+  // that pivot instead of building a second one.
+  if (plotColumns !== null && plotName !== null) columnsByName.set(plotName, plotColumns);
+  const { layerColumns, layerNames } = resolveLayerColumns(
+    layers,
+    datasets,
+    columnsByName,
+    countTable,
+  );
+
+  if (plotColumns === null && layerColumns.every((c) => c === null || c === "runtime")) {
+    return { status: "none" };
+  }
+
+  if (totalRows > limits.maxRows) {
+    return {
+      status: "errors",
+      errors: [
+        {
+          code: "validation-limit",
+          path: "/data",
+          message: `Inline data has ${totalRows} rows across plot/layers, more than the documented maxRows limit (${limits.maxRows}); data-aware checks skipped. Validate with a DataProfile instead.`,
+        },
+      ],
+    };
+  }
+  if (totalBytes > limits.maxBytes) {
+    return {
+      status: "errors",
+      errors: [
+        {
+          code: "validation-limit",
+          path: "/data",
+          message: `Inline data exceeds the documented maxBytes limit (${limits.maxBytes} bytes, estimated across plot/layers); data-aware checks skipped. Validate with a DataProfile instead.`,
+        },
+      ],
+    };
+  }
+
+  const plot = plotColumns === null ? null : evidenceFromColumns(plotColumns);
+  // Type inference walks every value of every column, so it too runs once per
+  // named dataset. The plot's own table seeds it, matching the row accounting
+  // above, which already treats a name the plot and a layer share as one table.
+  const evidenceByName = new Map<string, FieldEvidenceMap>();
+  if (plot !== null && plotName !== null) evidenceByName.set(plotName, plot);
+  const layerMaps: Array<FieldEvidenceMap | null> = layerColumns.map((cols, index) => {
+    if (cols === "runtime") return null;
+    if (cols === null) return plot;
+    const name = layerNames[index] ?? null;
+    if (name === null) return evidenceFromColumns(cols);
+    const cached = evidenceByName.get(name);
+    if (cached !== undefined) return cached;
+    const built = evidenceFromColumns(cols);
+    evidenceByName.set(name, built);
+    return built;
+  });
+  return { status: "ok", plot, layers: layerMaps };
+}
+
+function evidenceFromProfile(
+  profile: NonNullable<ValidateOptions["profile"]>,
+  spec: Record<string, unknown>,
+): ResolveLayerFieldEvidenceResult {
+  const bad = profileErrors(profile);
+  if (bad.length > 0) return { status: "errors", errors: bad };
+  const fields: FieldEvidenceMap = new Map();
+  for (const field of profile.fields) {
+    fields.set(field.name, { type: field.type, allNull: false, values: null, temporal: null });
+  }
+  const layers = Array.isArray(spec["layers"]) ? (spec["layers"] as unknown[]) : [];
+  return { status: "ok", plot: fields, layers: layers.map(() => fields) };
+}
+
+function resolveLayerColumns(
+  layers: unknown[],
+  datasets: unknown,
+  columnsByName: Map<string, Record<string, readonly CellValue[]>>,
+  countTable: (key: string, columns: Record<string, readonly CellValue[]>) => void,
+): {
+  layerColumns: Array<Record<string, readonly CellValue[]> | null | "runtime">;
+  layerNames: Array<string | null>;
+} {
+  const layerColumns: Array<Record<string, readonly CellValue[]> | null | "runtime"> = [];
+  const layerNames: Array<string | null> = [];
+  for (const layer of layers) {
+    if (!isRecord(layer) || layer["data"] === undefined) {
+      layerColumns.push(null);
+      layerNames.push(null);
+      continue;
+    }
+    const data = layer["data"];
+    const name = isRecord(data) && typeof data["name"] === "string" ? data["name"] : null;
+    let columns = name === null ? undefined : columnsByName.get(name);
+    if (columns === undefined) {
+      const resolved = columnsFromDataRef(data, datasets);
+      if (resolved === null) {
+        layerColumns.push("runtime");
+        layerNames.push(null);
+        continue;
+      }
+      columns = resolved;
+      if (name !== null) columnsByName.set(name, columns);
+    }
+    const key = name === null ? `inline:${layerColumns.length}` : `name:${name}`;
+    countTable(key, columns);
+    layerColumns.push(columns);
+    layerNames.push(name);
+  }
+  return { layerColumns, layerNames };
+}
+
+function estimateBytes(columns: Record<string, readonly CellValue[]>, rowCount: number): number {
+  // Estimate from a bounded sample so the limit check itself stays cheap.
+  const sample = Math.min(rowCount, 100);
+  if (sample === 0) return 0;
+  let sampleBytes = 0;
+  for (const column of Object.values(columns)) {
+    sampleBytes += JSON.stringify(column.slice(0, sample))?.length ?? 0;
+  }
+  return Math.round((sampleBytes / sample) * rowCount);
+}
+
+/**
+ * Resolve profile or inline data into a field evidence map (one pivot + type
+ * inference pass). Shared by dataChecks and lintSpec via validate().
+ */
+export function resolveFieldEvidence(
+  spec: Record<string, unknown>,
+  options: ValidateOptions,
+  limits: ValidateLimits,
+): ResolveFieldEvidenceResult {
+  if (options.profile !== undefined) {
+    const bad = profileErrors(options.profile);
+    if (bad.length > 0) return { status: "errors", errors: bad };
+    const fields: FieldEvidenceMap = new Map();
+    for (const f of options.profile.fields) {
+      fields.set(f.name, { type: f.type, allNull: false, values: null, temporal: null });
+    }
+    return { status: "ok", fields };
+  }
+
+  const columns = inlineColumns(spec);
+  if (columns === null) return { status: "none" };
+
+  const names = Object.keys(columns);
+  const rowCount = names.length === 0 ? 0 : (columns[names[0]!]?.length ?? 0);
+  if (rowCount > limits.maxRows) {
+    return {
+      status: "errors",
+      errors: [
+        {
+          code: "validation-limit",
+          path: "/data",
+          message: `Inline data has ${rowCount} rows, more than the documented maxRows limit (${limits.maxRows}); data-aware checks skipped. Validate with a DataProfile instead.`,
+        },
+      ],
+    };
+  }
+  if (estimateBytes(columns, rowCount) > limits.maxBytes) {
+    return {
+      status: "errors",
+      errors: [
+        {
+          code: "validation-limit",
+          path: "/data",
+          message: `Inline data exceeds the documented maxBytes limit (${limits.maxBytes} bytes, estimated); data-aware checks skipped. Validate with a DataProfile instead.`,
+        },
+      ],
+    };
+  }
+
+  const fields: FieldEvidenceMap = new Map();
+  for (const name of names) {
+    const column = columns[name]!;
+    const inferred = inferProfileType(column);
+    fields.set(name, {
+      type: inferred.type,
+      allNull: column.length > 0 && inferred.type === null,
+      values: column,
+      temporal: inferred.temporal,
+    });
+  }
+  return { status: "ok", fields };
+}

package/src/validate-data.ts

@@ -0,0 +1,114 @@
+/**
+ * Tier-2 validation public contract and re-exports.
+ *
+ * Plan: "Tier-2 accepts inline data OR a defined DataProfile". Runs when
+ * validate() receives an options argument.
+ *
+ * Implementation is split:
+ *  - validate-data-evidence.ts — FieldEvidenceMap construction + effectiveChannel
+ *  - validate-data-checks.ts — dataChecks orchestrator (evidence → walk → checkers)
+ *  - validate-data-checks-layer.ts — geom/stat rules + field walk + channel collection
+ *  - validate-data-checks-temporal.ts — shared temporalDecisionForField memoization
+ *  - validate-data-checks-position.ts — pre-evidence temporal config + x/y scale types
+ *  - validate-data-checks-color.ts — color/fill scale types + manual domain/range
+ *  - validate-data-checks-color-temporal.ts — temporal censor recovery lattice
+ *  - validate-data-checks-style.ts — shape/linetype + size/linewidth/alpha (finite + numeric modules)
+ *
+ * Style and color scale checks use per-layer evidenceForUse like position
+ * (#609 / #844) so multi-table same-name fields keep independent type views.
+ *
+ * Checks:
+ *  - field existence: every { field } channel must name an available field
+ *    (with a did-you-mean suggestion against the available names);
+ *  - all-null columns (inline data only) are tier-2 errors;
+ *  - { stat } channels must name a column the layer's stat generates
+ *    (identity generates none; count generates "count");
+ *  - scale/type compatibility: scales.*.type "time" needs temporal fields,
+ *    "log"/"linear" refuse nominal/ordinal fields, color/fill "sequential"
+ *    needs quantitative fields.
+ *
+ * Input limits (DEFAULT_VALIDATE_LIMITS — documented, overridable): agent-
+ * facing validation must not be resource-abusable. Over-limit inputs get a
+ * `validation-limit` diagnostic and the data-aware checks are skipped;
+ * diagnostics themselves are capped by maxDiagnostics (enforced in validate()).
+ */
+import type { JSONValue } from "./portability.js";
+
+// ---------------------------------------------------------------------------
+// Public contract
+// ---------------------------------------------------------------------------
+
+/** Field type vocabulary shared with agents (Vega-Lite-compatible names). */
+export type ProfileFieldType = "quantitative" | "temporal" | "ordinal" | "nominal";
+
+export interface DataProfileField {
+  name: string;
+  type: ProfileFieldType;
+  /** Optional example values (used in error messages, never validated). */
+  examples?: JSONValue[];
+}
+
+/** A description of out-of-band data, for validating specs without the data. */
+export interface DataProfile {
+  fields: DataProfileField[];
+  rowCount?: number;
+}
+
+/** Documented input limits for validate(). */
+export interface ValidateLimits {
+  /** Max inline-data rows examined (default 100_000). */
+  maxRows: number;
+  /** Max estimated inline-data bytes examined (default 20 MB). */
+  maxBytes: number;
+  /** Max JSON nesting depth of the spec (default 32). */
+  maxDepth: number;
+  /** Max diagnostics returned per run (default 100). */
+  maxDiagnostics: number;
+}
+
+export const DEFAULT_VALIDATE_LIMITS: ValidateLimits = {
+  maxRows: 100_000,
+  maxBytes: 20 * 1024 * 1024,
+  maxDepth: 32,
+  maxDiagnostics: 100,
+};
+
+export interface ValidateOptions {
+  /** Describe out-of-band data instead of inlining it. Wins over inline data. */
+  profile?: DataProfile;
+  /** Override the documented input limits. */
+  limits?: Partial<ValidateLimits>;
+  /** Also run lintSpec() and attach its advisories to the result (lint.ts). */
+  lint?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers owned by the public contract surface
+// ---------------------------------------------------------------------------
+
+/** Depth of a JSON-ish value, short-circuiting at `cap + 1`. */
+export function jsonDepth(value: unknown, cap: number): number {
+  if (typeof value !== "object" || value === null) return 0;
+  let max = 0;
+  const entries = Array.isArray(value) ? value : Object.values(value);
+  for (const child of entries) {
+    const d = jsonDepth(child, cap - 1);
+    if (d >= cap) return d + 1; // short-circuit: already too deep
+    if (d > max) max = d;
+  }
+  return max + 1;
+}
+
+// ---------------------------------------------------------------------------
+// Focused modules (re-exported so internal imports stay on this barrel)
+// ---------------------------------------------------------------------------
+
+export {
+  effectiveChannel,
+  resolveFieldEvidence,
+  resolveLayerFieldEvidence,
+  type FieldEvidenceEntry,
+  type FieldEvidenceMap,
+} from "./validate-data-evidence.js";
+
+export { dataChecks, STAT_COLUMNS } from "./validate-data-checks.js";