@ggts-sh/spec 0.43.0

package/src/validate-structure-scales.ts

@@ -0,0 +1,278 @@
+/**
+ * Data-free structural checks for named color/fill schemes vs scale family.
+ * Layer grammar: validate-structure-layers.ts (+ layer-rule/ribbon/computed-y). Facet: validate-structure-facet.ts.
+ */
+import type { SpecError } from "./errors.js";
+import {
+  CATEGORICAL_SCHEME_NAMES,
+  CYCLIC_SCHEME_NAMES,
+  SEQUENTIAL_SCHEME_NAMES,
+} from "./schema-names.js";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+const CATEGORICAL_SCHEMES = new Set<string>(CATEGORICAL_SCHEME_NAMES);
+const SEQUENTIAL_SCHEMES = new Set<string>(SEQUENTIAL_SCHEME_NAMES);
+const CYCLIC_SCHEMES = new Set<string>(CYCLIC_SCHEME_NAMES);
+
+/** Named color schemes must match the configured color scale family. */
+const GUIDE_AESTHETICS = [
+  "x",
+  "y",
+  "color",
+  "fill",
+  "size",
+  "linewidth",
+  "alpha",
+  "shape",
+  "linetype",
+] as const;
+
+/** Guide variants are constrained by aesthetic and explicit scale family. */
+export function guideStructuralErrors(
+  guides: Record<string, unknown>,
+  scales: Record<string, unknown> | undefined,
+): SpecError[] {
+  const errors: SpecError[] = [];
+  const check = (aesthetic: (typeof GUIDE_AESTHETICS)[number], guide: unknown, path: string) => {
+    if (!isRecord(guide) || typeof guide["type"] !== "string") return;
+    const type = guide["type"];
+    if (type === "none") return;
+    const scale = isRecord(scales?.[aesthetic]) ? scales?.[aesthetic] : undefined;
+    const scaleType = scale?.["type"];
+    if (guideIsValid(aesthetic, type, scaleType)) return;
+    errors.push({
+      code: "guide-aesthetic-incompatible",
+      path,
+      message: `The ${type} guide is incompatible with the ${aesthetic} aesthetic${typeof scaleType === "string" ? ` using a ${scaleType} scale` : ""}.`,
+      fix: {
+        description: guideFixDescription(aesthetic),
+      },
+    });
+  };
+  for (const aesthetic of GUIDE_AESTHETICS) {
+    const top = guides[aesthetic];
+    check(aesthetic, top, `/guides/${aesthetic}`);
+    const scale = scales?.[aesthetic];
+    if (top === undefined && isRecord(scale))
+      check(aesthetic, scale["guide"], `/scales/${aesthetic}/guide`);
+  }
+  return errors;
+}
+
+function guideIsValid(aesthetic: string, type: string, scaleType: unknown): boolean {
+  if (aesthetic === "x" || aesthetic === "y") return type === "axis";
+  if (aesthetic !== "color" && aesthetic !== "fill") return type === "legend";
+  if (type === "legend") return scaleType !== "sequential" && scaleType !== "binned";
+  if (type === "colorbar") return scaleType === undefined || scaleType === "sequential";
+  return type === "colorsteps" && scaleType === "binned";
+}
+
+function guideFixDescription(aesthetic: string): string {
+  if (aesthetic === "x" || aesthetic === "y") {
+    return 'Use { type: "axis" } or { type: "none" } for positional aesthetics.';
+  }
+  if (aesthetic === "color" || aesthetic === "fill") {
+    return "Use legend for discrete colors, colorbar for sequential colors, colorsteps for binned colors, or none.";
+  }
+  return 'Use { type: "legend" } or { type: "none" } for mapped style aesthetics.';
+}
+
+/** Named color schemes must match the configured color scale family. */
+export function colorScaleStructuralErrors(scales: Record<string, unknown>): SpecError[] {
+  const errors: SpecError[] = [];
+  for (const channel of ["color", "fill"] as const) {
+    const scale = scales[channel];
+    if (!isRecord(scale)) continue;
+    const type = scale["type"];
+    const scheme = scale["scheme"];
+    addBasicColorScaleErrors(errors, scale, channel, type);
+
+    addCyclicScaleErrors(errors, scale, channel, type, scheme);
+
+    if (
+      (type === "sequential" || type === "binned") &&
+      typeof scheme === "string" &&
+      CATEGORICAL_SCHEMES.has(scheme)
+    ) {
+      errors.push({
+        code: "scale-scheme-type",
+        path: `/scales/${channel}/scheme`,
+        message: `The categorical scheme "${scheme}" cannot be used with a ${type} color scale.`,
+        fix: {
+          description: 'Use "viridis" or provide a sequential range of #rgb/#rrggbb stops.',
+          example: "viridis",
+        },
+      });
+    } else if (type === "manual" && typeof scheme === "string" && SEQUENTIAL_SCHEMES.has(scheme)) {
+      // Ordinal may use sequential-family schemes (scale_*_viridis_d samples the
+      // ramp across the trained domain). Manual still rejects named schemes.
+      errors.push({
+        code: "scale-scheme-type",
+        path: `/scales/${channel}/scheme`,
+        message: `The sequential scheme "${scheme}" cannot be used with a manual color scale.`,
+        fix: {
+          description: "Use a categorical scheme or provide an ordinal range of CSS colors.",
+          example: "observable10",
+        },
+      });
+    }
+
+    const transform = scale["transform"];
+    const temporal = scale["temporalKind"] !== undefined || scale["parse"] !== undefined;
+    const describedType = typeof type === "string" ? type : "inferred";
+    if (
+      typeof transform === "string" &&
+      transform !== "identity" &&
+      (temporal || type === "ordinal" || type === "manual" || type === "identity")
+    ) {
+      errors.push({
+        code: "scale-type-transform-conflict",
+        path: `/scales/${channel}/transform`,
+        message: `The ${describedType} ${channel} scale cannot apply the ${transform} transform${temporal ? " to temporal values" : ""}.`,
+        fix: {
+          description:
+            "Remove the transform, or use a non-temporal sequential/binned quantitative scale.",
+          example: "identity",
+        },
+      });
+    }
+
+    addColorRangeErrors(errors, scale, channel, type);
+  }
+  return errors;
+}
+
+function addBasicColorScaleErrors(
+  errors: SpecError[],
+  scale: Record<string, unknown>,
+  channel: "color" | "fill",
+  type: unknown,
+): void {
+  if ("range" in scale && scale["range"] !== undefined && !Array.isArray(scale["range"])) {
+    errors.push({
+      code: "invalid-type",
+      path: `/scales/${channel}/range`,
+      message: `scales.${channel}.range must be an array of colors (got ${typeof scale["range"]}).`,
+      fix: {
+        description: "Provide range as a JSON array of #rgb/#rrggbb colors.",
+        example: ["#f00", "#0f0", "#00f"],
+      },
+    });
+  }
+  if (type === "binned" && scale["oob"] === "wrap") {
+    errors.push({
+      code: "scale-scheme-oob",
+      path: `/scales/${channel}/oob`,
+      message: `The binned ${channel} scale cannot use wrap out-of-bounds.`,
+      fix: {
+        description: 'Use "censor" or "squish" on binned color scales.',
+        example: "censor",
+      },
+    });
+  }
+}
+
+function addCyclicScaleErrors(
+  errors: SpecError[],
+  scale: Record<string, unknown>,
+  channel: "color" | "fill",
+  type: unknown,
+  scheme: unknown,
+): void {
+  if (typeof scheme !== "string" || !CYCLIC_SCHEMES.has(scheme)) return;
+  if (type !== undefined && type !== "sequential") {
+    const typeLabel = typeof type === "string" ? type : "this";
+    errors.push({
+      code: "scale-scheme-type",
+      path: `/scales/${channel}/scheme`,
+      message: `The cyclic scheme "${scheme}" cannot be used with a ${typeLabel} color scale.`,
+      fix: {
+        description: 'Use type "sequential" with an explicit domain period and oob "wrap".',
+        example: "sequential",
+      },
+    });
+  }
+  if (scale["oob"] === "censor" || scale["oob"] === "squish") {
+    errors.push({
+      code: "scale-scheme-oob",
+      path: `/scales/${channel}/oob`,
+      message: `The cyclic scheme "${scheme}" requires wrap out-of-bounds.`,
+      fix: {
+        description: 'Set oob to "wrap", or omit it (cyclic schemes default to wrap).',
+        example: "wrap",
+      },
+    });
+  }
+  if (!Array.isArray(scale["domain"]) || scale["domain"].length !== 2) {
+    errors.push({
+      code: "scale-cyclic-domain",
+      path: `/scales/${channel}/domain`,
+      message: `The cyclic scheme "${scheme}" requires an explicit two-value domain period.`,
+      fix: {
+        description: "Set domain to one period, for example [0, 360] for degrees.",
+        example: [0, 360],
+      },
+    });
+  }
+  if (scale["range"] !== undefined) {
+    errors.push({
+      code: "scale-scheme-type",
+      path: `/scales/${channel}/range`,
+      message: `The cyclic scheme "${scheme}" cannot be combined with an explicit range.`,
+      fix: { description: "Remove range and keep the named cyclic scheme, or drop the scheme." },
+    });
+  }
+  const transform = scale["transform"];
+  const temporal = scale["temporalKind"] !== undefined || scale["parse"] !== undefined;
+  if ((typeof transform === "string" && transform !== "identity") || temporal) {
+    errors.push({
+      code: "scale-type-transform-conflict",
+      path: `/scales/${channel}/transform`,
+      message: `The cyclic scheme "${scheme}" cannot apply a transform or temporal parser.`,
+      fix: {
+        description: "Remove transform and temporal options. Wrap in semantic space only.",
+        example: "identity",
+      },
+    });
+  }
+}
+
+function addColorRangeErrors(
+  errors: SpecError[],
+  scale: Record<string, unknown>,
+  channel: "color" | "fill",
+  type: unknown,
+): void {
+  const range = scale["range"];
+  const domain = scale["domain"];
+  if (
+    type === "manual" &&
+    Array.isArray(domain) &&
+    Array.isArray(range) &&
+    domain.length !== range.length
+  ) {
+    errors.push({
+      code: "color-manual-domain-range",
+      path: `/scales/${channel}`,
+      message: `The manual ${channel} scale has ${String(domain.length)} domain values but ${String(range.length)} range colors.`,
+      fix: { description: "Provide exactly one range color for each explicit domain value." },
+    });
+  }
+  if (!Array.isArray(range)) return;
+  for (let index = 0; index < range.length; index++) {
+    const color: unknown = range[index];
+    if (typeof color !== "string" || /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i.test(color)) continue;
+    errors.push({
+      code: "scale-range-color",
+      path: `/scales/${channel}/range/${index}`,
+      message: `The color stop "${color}" is not a supported hex color.`,
+      fix: {
+        description: "Use #rgb or #rrggbb syntax for custom color ranges.",
+        example: "#ff0000",
+      },
+    });
+  }
+}

package/src/validate-structure-style-bins.ts

@@ -0,0 +1,167 @@
+/**
+ * Structural well-formedness for binned numeric/finite style scales.
+ * Mirrors runtime checks in scale-style-numeric.ts / scale-style-finite.ts:
+ * authored breaks must be finite + strictly increasing, and when both domain
+ * and breaks are authored their endpoints must agree.
+ *
+ * Independent of parseFailure and of data — recovery bounds must themselves
+ * be valid or the runtime throws style-binned-breaks / style-domain-invalid.
+ */
+import type { SpecError } from "./errors.js";
+import { parseTemporalColumn } from "./temporal-column.js";
+import { parseTemporal } from "./temporal-parse.js";
+import { temporalParserUsable } from "./validate-data-checks-temporal.js";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+const BINNED_STYLE_AESTHETICS = ["size", "linewidth", "alpha", "shape", "linetype"] as const;
+
+/** Mirror core cellToNumber for non-temporal style boundary resolution. */
+function nonTemporalSemantic(value: unknown): number | undefined {
+  if (typeof value === "number") return Number.isFinite(value) ? value : undefined;
+  if (value instanceof Date) {
+    const epochMs = value.getTime();
+    return Number.isFinite(epochMs) ? epochMs : undefined;
+  }
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "string") {
+    const iso = parseTemporal(value, "iso");
+    if (iso.ok) return iso.epochMs;
+    if (value.trim() === "") return undefined;
+    const numeric = Number(value);
+    return Number.isFinite(numeric) ? numeric : undefined;
+  }
+  return undefined;
+}
+
+function resolveBoundarySemantics(
+  values: readonly unknown[],
+  config: Record<string, unknown>,
+): number[] | null {
+  const requestsTemporal =
+    config["temporalKind"] !== undefined ||
+    config["parse"] !== undefined ||
+    config["timezone"] !== undefined ||
+    config["disambiguation"] !== undefined;
+
+  if (!requestsTemporal) {
+    const mapped: number[] = [];
+    for (const value of values) {
+      const semantic = nonTemporalSemantic(value);
+      if (semantic === undefined) return null;
+      mapped.push(semantic);
+    }
+    return mapped;
+  }
+
+  // Schema-invalid temporal inputs still reach structure checks; defer rather
+  // than throw inside the temporal helpers (same gate as data-aware checks).
+  if (!temporalParserUsable(config["parse"])) return null;
+  if (config["timezone"] !== undefined && typeof config["timezone"] !== "string") return null;
+  if (config["disambiguation"] !== undefined && typeof config["disambiguation"] !== "string") {
+    return null;
+  }
+
+  const options = {
+    ...(typeof config["timezone"] === "string" && { timezone: config["timezone"] }),
+    ...(typeof config["disambiguation"] === "string" && {
+      disambiguation: config["disambiguation"] as "compatible" | "earlier" | "later" | "reject",
+    }),
+  };
+  const parser = (config["parse"] ?? "auto") as Parameters<typeof parseTemporalColumn>[1];
+  const column = parseTemporalColumn(values, parser, options);
+  const mapped: number[] = [];
+  for (let index = 0; index < values.length; index++) {
+    if (column.valid[index] !== 1) return null;
+    const epochMs = column.semantic[index];
+    if (epochMs === undefined || !Number.isFinite(epochMs)) return null;
+    mapped.push(epochMs);
+  }
+  return mapped;
+}
+
+function isStrictlyIncreasing(boundaries: readonly number[]): boolean {
+  for (let index = 1; index < boundaries.length; index++) {
+    const prev = boundaries[index - 1];
+    const current = boundaries[index];
+    if (prev === undefined || current === undefined || current <= prev) return false;
+  }
+  return true;
+}
+
+/**
+ * Config-only checks for binned size/linewidth/alpha/shape/linetype scales.
+ * Runs whenever the scale object is schema-valid (same cadence as color
+ * structural checks).
+ */
+export function binnedStyleScaleStructuralErrors(scales: Record<string, unknown>): SpecError[] {
+  const errors: SpecError[] = [];
+  for (const aesthetic of BINNED_STYLE_AESTHETICS) {
+    const config = scales[aesthetic];
+    if (!isRecord(config) || config["type"] !== "binned") continue;
+
+    const authoredBreaks = Array.isArray(config["breaks"]) ? config["breaks"] : undefined;
+    if (authoredBreaks === undefined) continue;
+
+    // Schema already enforces minItems: 2; still guard for partial schema paths.
+    if (authoredBreaks.length < 2) {
+      errors.push({
+        code: "scale-binned-breaks",
+        path: `/scales/${aesthetic}/breaks`,
+        message: `The ${aesthetic} boundaries must be finite and strictly increasing.`,
+        fix: {
+          description: "Provide at least two strictly increasing boundary values.",
+          example: [0, 10, 20],
+        },
+      });
+      continue;
+    }
+
+    const breakSemantics = resolveBoundarySemantics(authoredBreaks, config);
+    if (breakSemantics === null || !isStrictlyIncreasing(breakSemantics)) {
+      errors.push({
+        code: "scale-binned-breaks",
+        path: `/scales/${aesthetic}/breaks`,
+        message: `The ${aesthetic} boundaries must be finite and strictly increasing.`,
+        fix: {
+          description:
+            "Provide 2+ strictly increasing boundaries that parse under the scale's parser.",
+          example:
+            aesthetic === "size" || aesthetic === "linewidth" || aesthetic === "alpha"
+              ? [0, 10, 20]
+              : [0, 1, 2],
+        },
+      });
+      // Malformed breaks are the primary diagnostic; skip domain agreement.
+      continue;
+    }
+
+    const domain = Array.isArray(config["domain"]) ? config["domain"] : undefined;
+    if (domain === undefined || domain.length !== 2) continue;
+
+    const domainSemantics = resolveBoundarySemantics(domain, config);
+    if (domainSemantics === null || domainSemantics.length !== 2) {
+      // Unparseable domain is a separate runtime style-domain-invalid path; the
+      // censor-recovery check covers type-mismatch. Only emit agreement here when
+      // both sides fully resolve.
+      continue;
+    }
+
+    const first = breakSemantics[0]!;
+    const last = breakSemantics.at(-1)!;
+    if (domainSemantics[0] !== first || domainSemantics[1] !== last) {
+      errors.push({
+        code: "scale-binned-domain",
+        path: `/scales/${aesthetic}/domain`,
+        message: `The ${aesthetic} binned domain must match its first and last boundaries.`,
+        fix: {
+          description: "Set domain to the first and last break values, or omit domain.",
+          example: [first, last],
+        },
+      });
+    }
+  }
+  return errors;
+}

package/src/validate-structure.ts

@@ -0,0 +1,16 @@
+/**
+ * Data-free structural grammar checks (tier-2, opt-in via validate options).
+ *
+ * Implementation:
+ *  - validate-structure-layers.ts — geom channels, rule/ribbon/computed-y forms, M2 layer rules
+ *  - validate-structure-scales.ts — named color/fill scheme vs family
+ *  - validate-structure-style-bins.ts — binned style breaks/domain well-formedness
+ *  - validate-structure-facet.ts — wrap XOR grid form
+ *
+ * Used only by validate() — not public surface.
+ */
+
+export { layerStructuralErrors } from "./validate-structure-layers.js";
+export { colorScaleStructuralErrors, guideStructuralErrors } from "./validate-structure-scales.js";
+export { binnedStyleScaleStructuralErrors } from "./validate-structure-style-bins.js";
+export { coordFacetStructuralErrors, facetStructuralErrors } from "./validate-structure-facet.js";

package/src/validate.ts

@@ -0,0 +1,212 @@
+/**
+ * Spec validation orchestrator — tier 1 (schema shape) plus opt-in tier 2
+ * (structural grammar, data-aware checks, optional lint).
+ *
+ * Tier-1 mechanism (decision 0004): TypeBox 1.x compiled checks plus
+ * `Value.Errors` over the same schemas that emit `schema/v0.json` — one
+ * artifact, no drift.
+ * Layer/plot shape walks: validate-schema-shape.ts (shared GEOM_BRANCHES;
+ * also hands per-layer branch-ok indices to the tier-2 structural gate).
+ * Raw TypeBox union noise is mapped to the agent error contract in
+ * validate-map-errors.ts (schema walk: validate-schema-walk.ts; channel/data
+ * form classification: validate-map-forms.ts).
+ * Data-free grammar rules live in validate-structure*.ts (layers / color
+ * schemes / facet form). Data-aware checks live in validate-data*.ts
+ * (evidence + checks modules, barrel at validate-data.ts).
+ *
+ * Output: `{ ok: true, spec }` or `{ ok: false, errors: SpecError[] }` with
+ * the agent error contract from errors.ts. Messages are snapshot-tested.
+ */
+import { Settings } from "typebox/system";
+
+import type { SpecError } from "./errors.js";
+// Precompiled at build time (scripts/gen-plot-validator.ts) — compiling the
+// full plot union at runtime costs seconds; the generated module is pinned
+// against a runtime-compiled validator by plot-spec-validator-generated.test.
+import { Check as plotSpecSchemaCheck } from "./generated/plot-spec-validator.js";
+import type { SpecAdvisory } from "./lint.js";
+import { lintSpec } from "./lint.js";
+import type { Aes, PortableSpec } from "./schema.js";
+import { ensureTemporalPolyfill } from "./temporal-polyfill.js";
+import type { ValidateOptions } from "./validate-data.js";
+import {
+  dataChecks,
+  DEFAULT_VALIDATE_LIMITS,
+  jsonDepth,
+  resolveLayerFieldEvidence,
+} from "./validate-data.js";
+import { collectSchemaShapeErrors, GEOM_BRANCHES } from "./validate-schema-shape.js";
+import { structuralGateErrors } from "./structural-gate.js";
+import { facetStructuralErrors, layerStructuralErrors } from "./validate-structure.js";
+
+export type ValidateResult =
+  | { ok: true; spec: PortableSpec; advisories?: SpecAdvisory[] }
+  | { ok: false; errors: SpecError[]; advisories?: SpecAdvisory[] };
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Validate a spec. Tier 1 (always): schema shape, no data needed. Tier 2
+ * (opt-in — pass an `options` argument, even `{}`): the grammar's structural
+ * rules (required channels per geom, bar/count y ban, rule forms) plus
+ * data-aware checks against the spec's inline data or the provided
+ * DataProfile, under documented input limits (DEFAULT_VALIDATE_LIMITS).
+ *
+ * On success, returns the input typed as PortableSpec (no copy is made).
+ */
+export function validate(input: unknown, options?: ValidateOptions): ValidateResult {
+  // Agent validate path may inspect temporal columns / IANA zones — load the
+  // polyfill here so lean `@ggts-sh/core/render` graphs never need it.
+  ensureTemporalPolyfill();
+  const limits = { ...DEFAULT_VALIDATE_LIMITS, ...options?.limits };
+
+  // Depth guard first: pathological nesting must not reach the schema walker.
+  if (jsonDepth(input, limits.maxDepth) > limits.maxDepth) {
+    return {
+      ok: false,
+      errors: [
+        {
+          code: "validation-limit",
+          path: "",
+          message: `The spec nests deeper than ${limits.maxDepth} levels (documented maxDepth limit); validation refused.`,
+        },
+      ],
+    };
+  }
+
+  const errors: SpecError[] = [];
+  // TypeBox Settings are process-global. Align with tsconfig exactOptionalPropertyTypes
+  // and raise maxErrors so Value.Errors is not truncated at the default of 8.
+  const previousMaxErrors = Settings.Get().maxErrors;
+  const previousExactOptional = Settings.Get().exactOptionalPropertyTypes;
+  Settings.Set({
+    maxErrors: Math.max(limits.maxDiagnostics, previousMaxErrors),
+    exactOptionalPropertyTypes: true,
+  });
+  try {
+    // TypeBox's interpreted Value.Check / Value.Errors walk the cyclic schema
+    // graph for every inline row. Use the compiled plot validator for the
+    // common valid path, and Value.Errors only when building invalid diagnostics.
+    const schemaValid: boolean = (plotSpecSchemaCheck as (value: unknown) => boolean)(input);
+
+    // Tier-2 structural gate: run layerStructuralErrors only on branch-valid
+    // layers. When the compiled plot check passed, LayerSpec's geom-discriminated
+    // union already proves every layer matches its GEOM_BRANCHES member — skip
+    // a second interpreted walk. When it failed, reuse the shape walk's per-layer
+    // Value.Errors emptiness set (#1279).
+    let branchOkLayers: ReadonlySet<number> | "all" = "all";
+
+    if (!schemaValid) {
+      if (!isRecord(input)) {
+        return {
+          ok: false,
+          errors: [
+            {
+              code: "invalid-spec-root",
+              path: "",
+              message: `A plot spec must be a JSON object with a "layers" array (got ${Array.isArray(input) ? "an array" : typeof input}).`,
+              fix: {
+                description: "Provide an object with at least one layer.",
+                example: {
+                  layers: [{ geom: "point", aes: { x: { field: "x" }, y: { field: "y" } } }],
+                },
+              },
+            },
+          ],
+        };
+      }
+
+      const shape = collectSchemaShapeErrors(input);
+      errors.push(...shape.errors);
+      branchOkLayers = shape.branchOkLayerIndices;
+    }
+
+    // TypeBox-free structural gates (shared with pipeline render path).
+    if (schemaValid) {
+      errors.push(...structuralGateErrors(input));
+    }
+
+    // --- tier 2 (opt-in via options): structural grammar checks ----------------
+    // Required channels, the bar/count y ban, and the rule form rules are part
+    // of the tier-2 contract (the pipeline enforces them at render time with
+    // equivalent structured errors); tier 1 stays schema-shape-only so partial
+    // specs remain composable.
+    // Eligibility: record layers with a known geom whose branch is valid
+    // (see branchOkLayers above). Uses shared GEOM_BRANCHES for known-geom keys.
+    // --- tier 2 (opt-in): facet form rules --------------------------------------
+    // Runs for any record-valued facet, even when the facet is schema-invalid.
+    errors.push(
+      ...collectLayerGrammarErrors(input, options, branchOkLayers),
+      ...collectFacetGrammarErrors(input, options),
+    );
+
+    // --- tier 2 (opt-in): data-aware checks + optional lint --------------------
+    // One resolveLayerFieldEvidence pass for plot + layer tables; dataChecks and
+    // lintSpec share it. On limit/profile errors, lint gets no shared map so it
+    // does not re-scan data that data-aware validation already refused.
+    const advisories = collectDataValidation(input, options, limits, errors);
+    const withAdvisories = advisories !== undefined && advisories.length > 0 ? { advisories } : {};
+
+    if (errors.length > limits.maxDiagnostics) {
+      const kept = errors.slice(0, limits.maxDiagnostics);
+      kept.push({
+        code: "validation-limit",
+        path: "",
+        message: `Diagnostics truncated: ${errors.length} problems found, showing the first ${limits.maxDiagnostics} (documented maxDiagnostics limit).`,
+      });
+      return { ok: false, errors: kept, ...withAdvisories };
+    }
+
+    if (errors.length > 0) return { ok: false, errors, ...withAdvisories };
+    return { ok: true, spec: input as PortableSpec, ...withAdvisories };
+  } finally {
+    Settings.Set({
+      maxErrors: previousMaxErrors,
+      exactOptionalPropertyTypes: previousExactOptional,
+    });
+  }
+}
+
+function collectLayerGrammarErrors(
+  input: unknown,
+  options: ValidateOptions | undefined,
+  branchOkLayers: ReadonlySet<number> | "all",
+): SpecError[] {
+  if (options === undefined || !isRecord(input) || !Array.isArray(input["layers"])) return [];
+  const errors: SpecError[] = [];
+  const plotAes = isRecord(input["aes"]) ? (input["aes"] as Aes) : undefined;
+  const layers = input["layers"] as unknown[];
+  for (let index = 0; index < layers.length; index++) {
+    const layer = layers[index];
+    if (!isRecord(layer)) continue;
+    const geom = layer["geom"];
+    if (typeof geom !== "string" || !Object.hasOwn(GEOM_BRANCHES, geom)) continue;
+    if (branchOkLayers !== "all" && !branchOkLayers.has(index)) continue;
+    errors.push(...layerStructuralErrors(layer, geom, index, plotAes));
+  }
+  return errors;
+}
+
+function collectFacetGrammarErrors(
+  input: unknown,
+  options: ValidateOptions | undefined,
+): SpecError[] {
+  if (options === undefined || !isRecord(input) || !isRecord(input["facet"])) return [];
+  return facetStructuralErrors(input["facet"]);
+}
+
+function collectDataValidation(
+  input: unknown,
+  options: ValidateOptions | undefined,
+  limits: typeof DEFAULT_VALIDATE_LIMITS,
+  errors: SpecError[],
+): SpecAdvisory[] | undefined {
+  if (options === undefined || !isRecord(input)) return undefined;
+  const layerResolved = resolveLayerFieldEvidence(input, options, limits);
+  errors.push(...dataChecks(input, options, limits, layerResolved));
+  if (options.lint !== true) return undefined;
+  const shared = layerResolved.status === "ok" ? layerResolved.plot : null;
+  return lintSpec(input, options, shared);
+}