@ggts-sh/spec 0.43.0

package/src/validate-schema-shape.ts

@@ -0,0 +1,232 @@
+/**
+ * Tier-1 schema shape walk: discriminator-aware layer branches + plot shell.
+ *
+ * Shared geom branch lookup (`GEOM_BRANCHES`) is also used by validate() to
+ * recognise known geoms for the tier-2 structural gate. Branch validity for
+ * that gate comes from the compiled plot check (valid path) or from this
+ * walk's per-layer `Value.Errors` result (invalid path) — not a second
+ * interpreted `Value.Check` per layer (#1279).
+ *
+ * Orchestrator: validate.ts. Error mapping: validate-map-errors.ts.
+ */
+import { Value } from "typebox/value";
+
+import type { SpecError } from "./errors.js";
+import {
+  AreaLayerSchema,
+  BarLayerSchema,
+  BoxplotLayerSchema,
+  ColLayerSchema,
+  DensityLayerSchema,
+  Density2dLayerSchema,
+  Density2dFilledLayerSchema,
+  DotplotLayerSchema,
+  ErrorbarLayerSchema,
+  LinerangeLayerSchema,
+  PointrangeLayerSchema,
+  CrossbarLayerSchema,
+  HistogramLayerSchema,
+  FreqpolyLayerSchema,
+  HlineLayerSchema,
+  JitterLayerSchema,
+  LineLayerSchema,
+  PathLayerSchema,
+  PlotSpecSchema,
+  PointLayerSchema,
+  RasterLayerSchema,
+  HexLayerSchema,
+  RectLayerSchema,
+  RibbonLayerSchema,
+  SegmentLayerSchema,
+  CountLayerSchema,
+  ViolinLayerSchema,
+  FunctionLayerSchema,
+  PolygonLayerSchema,
+  AblineLayerSchema,
+  CurveLayerSchema,
+  MapLayerSchema,
+  BlankLayerSchema,
+  SfLayerSchema,
+  SfTextLayerSchema,
+  SfLabelLayerSchema,
+  SpokeLayerSchema,
+  RugLayerSchema,
+  StepLayerSchema,
+  QqLayerSchema,
+  QqLineLayerSchema,
+  RuleLayerSchema,
+  QuantileLayerSchema,
+  ContourLayerSchema,
+  SmoothLayerSchema,
+  TextLayerSchema,
+  LabelLayerSchema,
+  TileLayerSchema,
+  Bin2dLayerSchema,
+  VlineLayerSchema,
+} from "./schema.js";
+import { mapValueErrors, unknownGeomError } from "./validate-map-errors.js";
+
+/** Known geom → layer schema for branch-selected tier-1 walks and tier-2 eligibility. */
+export const GEOM_BRANCHES = {
+  point: PointLayerSchema,
+  line: LineLayerSchema,
+  path: PathLayerSchema,
+  col: ColLayerSchema,
+  bar: BarLayerSchema,
+  histogram: HistogramLayerSchema,
+  freqpoly: FreqpolyLayerSchema,
+  area: AreaLayerSchema,
+  ribbon: RibbonLayerSchema,
+  segment: SegmentLayerSchema,
+  count: CountLayerSchema,
+  violin: ViolinLayerSchema,
+  function: FunctionLayerSchema,
+  polygon: PolygonLayerSchema,
+  abline: AblineLayerSchema,
+  curve: CurveLayerSchema,
+  map: MapLayerSchema,
+  blank: BlankLayerSchema,
+  sf: SfLayerSchema,
+  sf_text: SfTextLayerSchema,
+  sf_label: SfLabelLayerSchema,
+
+  spoke: SpokeLayerSchema,
+  rug: RugLayerSchema,
+  step: StepLayerSchema,
+  qq: QqLayerSchema,
+  qq_line: QqLineLayerSchema,
+  rule: RuleLayerSchema,
+  hline: HlineLayerSchema,
+  vline: VlineLayerSchema,
+  jitter: JitterLayerSchema,
+  text: TextLayerSchema,
+  label: LabelLayerSchema,
+  smooth: SmoothLayerSchema,
+  quantile: QuantileLayerSchema,
+  contour: ContourLayerSchema,
+  boxplot: BoxplotLayerSchema,
+  density: DensityLayerSchema,
+  density_2d: Density2dLayerSchema,
+  density_2d_filled: Density2dFilledLayerSchema,
+  dotplot: DotplotLayerSchema,
+  errorbar: ErrorbarLayerSchema,
+  linerange: LinerangeLayerSchema,
+  pointrange: PointrangeLayerSchema,
+  crossbar: CrossbarLayerSchema,
+  rect: RectLayerSchema,
+  tile: TileLayerSchema,
+  bin_2d: Bin2dLayerSchema,
+  raster: RasterLayerSchema,
+  hex: HexLayerSchema,
+} as const;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** One layer's tier-1 shape errors plus whether its geom branch was clean. */
+type LayerShapeResult = {
+  errors: SpecError[];
+  /** True when `Value.Errors(branch, layer)` was empty (branch-valid). */
+  branchOk: boolean;
+};
+
+/** Discriminator-aware layer walk — one layer's tier-1 shape errors. */
+function mapLayerShapeErrors(layer: unknown, layerPath: string): LayerShapeResult {
+  if (!isRecord(layer)) {
+    return {
+      branchOk: false,
+      errors: [
+        {
+          code: "invalid-layer",
+          path: layerPath,
+          message: `Each layer must be an object with a "geom" (got ${typeof layer}).`,
+          fix: { description: "Replace with a layer object.", example: { geom: "point" } },
+        },
+      ],
+    };
+  }
+  const geom = layer["geom"];
+  // Own-key check: `in` walks the prototype chain, so a geom named
+  // "constructor" would pass this guard and hand Value.Errors a function
+  // instead of a schema — reporting invalid-type rather than the did-you-mean.
+  if (typeof geom !== "string" || !Object.hasOwn(GEOM_BRANCHES, geom)) {
+    return { branchOk: false, errors: [unknownGeomError(geom, layerPath)] };
+  }
+  const branch = GEOM_BRANCHES[geom as keyof typeof GEOM_BRANCHES];
+  const raw = Value.Errors(branch, layer);
+  return {
+    branchOk: raw.length === 0,
+    errors: mapValueErrors(raw, {
+      schema: branch,
+      value: layer,
+      pathPrefix: layerPath,
+    }),
+  };
+}
+
+/** Result of the tier-1 shape walk for one invalid plot. */
+export type SchemaShapeResult = {
+  errors: SpecError[];
+  /**
+   * Layer indices whose geom-branch `Value.Errors` walk was empty. Used by
+   * validate() so the tier-2 structural gate does not re-run interpreted
+   * `Value.Check` on the same layers.
+   */
+  branchOkLayerIndices: ReadonlySet<number>;
+};
+
+/**
+ * Tier-1 schema walk (caller must set TypeBox Settings for the process).
+ * Layer branch walk + plot-level shell so layer noise is not double-reported.
+ */
+export function collectSchemaShapeErrors(input: Record<string, unknown>): SchemaShapeResult {
+  const errors: SpecError[] = [];
+  const branchOkLayerIndices = new Set<number>();
+  const layers = input["layers"];
+  if (!Array.isArray(layers)) {
+    errors.push({
+      code: "missing-layers",
+      path: "/layers",
+      message: `"layers" must be an array of layer objects (got ${layers === undefined ? "nothing" : typeof layers}).`,
+      fix: {
+        description: "Add a layers array with at least one layer.",
+        example: [{ geom: "point" }],
+      },
+    });
+  } else if (layers.length === 0) {
+    errors.push({
+      code: "empty-layers",
+      path: "/layers",
+      message: '"layers" must contain at least one layer.',
+      fix: { description: "Add a layer.", example: [{ geom: "point" }] },
+    });
+  } else {
+    for (let i = 0; i < layers.length; i++) {
+      const layerResult = mapLayerShapeErrors(layers[i], `/layers/${i}`);
+      if (layerResult.branchOk) branchOkLayerIndices.add(i);
+      errors.push(...layerResult.errors);
+    }
+  }
+
+  // Plot-level walk with a known-valid layer shell so layer noise is not
+  // re-reported alongside the branch-selected layer walk above.
+  const shell = { ...input, layers: [{ geom: "point" }] };
+  errors.push(
+    ...mapValueErrors(Value.Errors(PlotSpecSchema, shell), {
+      schema: PlotSpecSchema,
+      value: shell,
+      pathPrefix: "",
+    }),
+  );
+
+  if (errors.length === 0) {
+    // Compiled plot Check failed but neither walk produced a mapped error.
+    errors.push({
+      code: "invalid-type",
+      path: "",
+      message: "The spec does not match the schema.",
+    });
+  }
+  return { errors, branchOkLayerIndices };
+}

package/src/validate-schema-walk.ts

@@ -0,0 +1,219 @@
+/**
+ * TypeBox Cyclic schema / instance-path inspection helpers for tier-1 error mapping.
+ *
+ * JSON-pointer reads against the validated value, `$defs`/`$ref` walking along
+ * instancePath and schemaPath, union-member inspection, and small schema-shape
+ * queries. Used only by validate-map-errors.ts — not public package surface.
+ */
+
+export function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+export function lastSegment(path: string): string {
+  const i = path.lastIndexOf("/");
+  return i === -1 ? path : path.slice(i + 1);
+}
+
+export function pathSegments(path: string): string[] {
+  return path.split("/").filter((s) => s.length > 0);
+}
+
+/** JSON-pointer get (instancePath form: `/a/b/0`). */
+export function pointerGet(root: unknown, path: string): unknown {
+  if (path === "" || path === "/") return root;
+  let cur: unknown = root;
+  for (const seg of pathSegments(path)) {
+    if (cur === null || cur === undefined) return undefined;
+    if (Array.isArray(cur)) {
+      const i = Number(seg);
+      cur = Number.isInteger(i) ? cur[i] : undefined;
+      continue;
+    }
+    if (!isRecord(cur)) return undefined;
+    cur = cur[seg];
+  }
+  return cur;
+}
+
+/** Resolve the root object schema of a TypeBox Cyclic (`$defs` + `$ref`). */
+function cyclicRootSchema(schema: unknown): Record<string, unknown> | null {
+  if (!isRecord(schema)) return null;
+  const defs = schema["$defs"];
+  const ref = schema["$ref"];
+  if (isRecord(defs) && typeof ref === "string" && isRecord(defs[ref])) {
+    return defs[ref];
+  }
+  return isRecord(schema) ? schema : null;
+}
+
+function resolveRef(
+  node: Record<string, unknown>,
+  defs: Record<string, unknown> | null,
+): Record<string, unknown> {
+  const ref = node["$ref"];
+  if (typeof ref !== "string" || defs === null) return node;
+  // TypeBox emits bare names ("PointParams") and sometimes JSON pointers.
+  const name = ref.startsWith("#/$defs/")
+    ? ref.slice("#/$defs/".length)
+    : ref.startsWith("#/")
+      ? null
+      : ref;
+  if (name !== null && isRecord(defs[name])) return defs[name];
+  return node;
+}
+
+/**
+ * Walk a Cyclic schema along an instance path, returning the schema that
+ * describes the value at that path (after following $refs).
+ */
+export function schemaAtInstancePath(rootSchema: unknown, instancePath: string): unknown {
+  const root = cyclicRootSchema(rootSchema);
+  if (root === null) return null;
+  const defs = isRecord(rootSchema) && isRecord(rootSchema["$defs"]) ? rootSchema["$defs"] : null;
+  let node: Record<string, unknown> = root;
+  for (const seg of pathSegments(instancePath)) {
+    node = resolveRef(node, defs);
+    const props = node["properties"];
+    if (isRecord(props) && isRecord(props[seg])) {
+      node = props[seg];
+      continue;
+    }
+    // Array index: follow `items` (object or tuple entry).
+    if (/^\d+$/.test(seg)) {
+      const items = node["items"];
+      if (isRecord(items)) {
+        node = items;
+        continue;
+      }
+      if (Array.isArray(items)) {
+        const entry: unknown = items[Number(seg)];
+        if (isRecord(entry)) {
+          node = entry;
+          continue;
+        }
+      }
+    }
+    // additionalProperties / patternProperties value schemas
+    if (isRecord(node["additionalProperties"])) {
+      node = node["additionalProperties"];
+      continue;
+    }
+    return null;
+  }
+  return resolveRef(node, defs);
+}
+
+/**
+ * Resolve a TypeBox-relative schemaPath (`#/properties/x/anyOf/0`) against
+ * the schema that applies at `instancePath`'s parent object context.
+ * For Cyclic validation, `#` is relative to the nearest $ref target; we
+ * approximate by resolving at the instancePath node, then walking the path.
+ */
+export function schemaAtSchemaPath(
+  rootSchema: unknown,
+  instancePath: string,
+  schemaPath: string,
+): unknown {
+  // Most useful cases: `#` means the schema of the instance node itself
+  // (e.g. additionalProperties on PointParams when instancePath is /params).
+  const base = schemaAtInstancePath(rootSchema, instancePath);
+  if (schemaPath === "#" || schemaPath === "") return base;
+
+  const defs = isRecord(rootSchema) && isRecord(rootSchema["$defs"]) ? rootSchema["$defs"] : null;
+
+  const parts = schemaPath
+    .replace(/^#\/?/, "")
+    .split("/")
+    .filter((p) => p.length > 0);
+  // If walking from base fails, fall back to walking from cyclic root def.
+  const tryWalk = (start: unknown): unknown => {
+    let cur = start;
+    for (const p of parts) {
+      if (cur === null || cur === undefined) return null;
+      if (Array.isArray(cur) && /^\d+$/.test(p)) {
+        cur = cur[Number(p)];
+        continue;
+      }
+      if (!isRecord(cur)) return null;
+      const rec = resolveRef(cur, defs);
+      cur = rec[p];
+    }
+    return isRecord(cur) ? resolveRef(cur, defs) : cur;
+  };
+
+  const fromBase = tryWalk(base);
+  if (fromBase !== null && fromBase !== undefined) return fromBase;
+  const fromRoot = tryWalk(cyclicRootSchema(rootSchema));
+  if (fromRoot !== null && fromRoot !== undefined) return fromRoot;
+  // TypeBox 1 schemaPath is often relative to a $defs member (e.g. DataValues),
+  // not the Cyclic plot root — try each def as a base.
+  if (defs !== null) {
+    for (const def of Object.values(defs)) {
+      if (!isRecord(def)) continue;
+      const hit = tryWalk(def);
+      if (hit !== null && hit !== undefined) return hit;
+    }
+  }
+  return null;
+}
+
+export interface UnionMemberInfo {
+  refs: string[];
+  consts: string[];
+  allConst: boolean;
+}
+
+export function unionMembers(schema: unknown): UnionMemberInfo {
+  const info: UnionMemberInfo = { refs: [], consts: [], allConst: true };
+  const anyOf =
+    isRecord(schema) && Array.isArray(schema["anyOf"]) ? (schema["anyOf"] as unknown[]) : [];
+  for (const member of anyOf) {
+    if (!isRecord(member)) continue;
+    const ref = member["$ref"];
+    if (typeof ref === "string") info.refs.push(ref.replace(/^#\/\$defs\//, ""));
+    const c = member["const"];
+    if (typeof c === "string" || typeof c === "number" || typeof c === "boolean") {
+      info.consts.push(String(c));
+    } else {
+      // nested anyOf of literals still counts as all-const if every branch is const
+      if (Array.isArray(member["anyOf"])) {
+        const nested = unionMembers(member);
+        if (nested.allConst && nested.consts.length > 0) {
+          info.consts.push(...nested.consts);
+          continue;
+        }
+      }
+      info.allConst = false;
+    }
+  }
+  if (anyOf.length === 0) info.allConst = false;
+  return info;
+}
+
+export function additionalPropertiesIsClosed(objectSchema: unknown): boolean {
+  if (!isRecord(objectSchema)) return true;
+  const ap = objectSchema["additionalProperties"];
+  // Explicit schema (object / boolean true) means keys are allowed; false/absent = closed.
+  if (ap === false || ap === undefined) return true;
+  if (ap === true) return false;
+  return typeof ap !== "object" || ap === null;
+}
+
+export function objectPropertyNames(schema: unknown): string[] {
+  if (!isRecord(schema)) return [];
+  const props = schema["properties"];
+  return isRecord(props) ? Object.keys(props) : [];
+}
+
+export function numberBounds(schema: unknown): string[] {
+  if (!isRecord(schema)) return [];
+  const bounds: string[] = [];
+  if (typeof schema["minimum"] === "number") bounds.push(`>= ${schema["minimum"]}`);
+  if (typeof schema["exclusiveMinimum"] === "number")
+    bounds.push(`> ${schema["exclusiveMinimum"]}`);
+  if (typeof schema["maximum"] === "number") bounds.push(`<= ${schema["maximum"]}`);
+  if (typeof schema["exclusiveMaximum"] === "number")
+    bounds.push(`< ${schema["exclusiveMaximum"]}`);
+  return bounds;
+}

package/src/validate-structure-facet.ts

@@ -0,0 +1,76 @@
+/**
+ * Data-free structural checks for facet wrap XOR grid form.
+ * Layer grammar: validate-structure-layers.ts (+ layer-rule/ribbon/computed-y). Color schemes: validate-structure-scales.ts.
+ */
+import type { SpecError } from "./errors.js";
+
+export function coordFacetStructuralErrors(input: Record<string, unknown>): SpecError[] {
+  const coord = input["coord"];
+  const facet = input["facet"];
+  if (
+    typeof coord !== "object" ||
+    coord === null ||
+    Array.isArray(coord) ||
+    typeof facet !== "object" ||
+    facet === null ||
+    Array.isArray(facet)
+  ) {
+    return [];
+  }
+  const coordType = (coord as Record<string, unknown>)["type"];
+  if (coordType !== "fixed" && coordType !== "sf" && coordType !== "radial") return [];
+  const scales = (facet as Record<string, unknown>)["scales"];
+  if (scales === undefined || scales === "fixed") return [];
+  const coordName =
+    coordType === "sf" ? "coord_sf" : coordType === "radial" ? "coord_radial" : "coord_fixed";
+  return [
+    {
+      code: "coord-fixed-free-scales",
+      path: "/facet/scales",
+      message: `${coordName} cannot use facet scales ${JSON.stringify(scales)} because panels would imply unequal physical data-unit lengths.`,
+      fix: {
+        description: `Use facet.scales = "fixed", or remove the ${coordName} coordinate.`,
+        example: "fixed",
+      },
+    },
+  ];
+}
+
+export function facetStructuralErrors(facet: Record<string, unknown>): SpecError[] {
+  const errors: SpecError[] = [];
+  const hasWrap = facet["wrap"] !== undefined;
+  const hasGrid = facet["rows"] !== undefined || facet["cols"] !== undefined;
+  if (hasWrap && hasGrid) {
+    errors.push({
+      code: "facet-form-ambiguous",
+      path: "/facet",
+      message:
+        "This facet mixes the wrap form (facet.wrap) with the grid form (facet.rows/facet.cols). Use wrap OR rows/cols, never both.",
+      fix: {
+        description: "Keep facet.wrap (and drop rows/cols), or keep rows/cols (and drop wrap).",
+        example: { wrap: { field: "group" }, ncol: 3 },
+      },
+    });
+  } else if (!hasWrap && !hasGrid) {
+    errors.push({
+      code: "facet-form-missing",
+      path: "/facet",
+      message:
+        "This facet sets neither wrap nor rows/cols — there is no field to partition panels by.",
+      fix: {
+        description: "Set facet.wrap (wrap form) or facet.rows/facet.cols (grid form).",
+        example: { wrap: { field: "group" } },
+      },
+    });
+  }
+  if (facet["ncol"] !== undefined && !hasWrap) {
+    errors.push({
+      code: "facet-ncol-without-wrap",
+      path: "/facet/ncol",
+      message:
+        "facet.ncol only applies to the wrap form; the grid form's columns come from facet.cols' distinct values.",
+      fix: { description: "Remove ncol, or switch to the wrap form." },
+    });
+  }
+  return errors;
+}

package/src/validate-structure-layer-computed-y.ts

@@ -0,0 +1,94 @@
+/**
+ * computed-y-mapped structural checks for geoms/stats that own y.
+ * Orchestrated by validate-structure-layers.ts.
+ *
+ * Each geom/stat family is checked independently (same as the pre-split
+ * sequential ifs) so an odd pairing can still emit more than one error.
+ */
+import type { SpecError } from "./errors.js";
+import type { ChannelName, ChannelValue } from "./schema.js";
+
+/** Reject data-mapped y when the geom/stat computes y. */
+export function computedYMappedErrors(
+  geom: string,
+  stat: string,
+  layerPath: string,
+  /** Same shape as `effectiveChannel` — null unset already collapsed to undefined. */
+  mapped: (channel: ChannelName) => Exclude<ChannelValue, null> | undefined,
+): SpecError[] {
+  const errors: SpecError[] = [];
+  const y = mapped("y");
+  // Unmapped or after_stat form ({ stat }) is fine; data-mapped y is not.
+  if (y === undefined || "stat" in y) return errors;
+
+  if (
+    geom === "bar" ||
+    geom === "histogram" ||
+    geom === "freqpoly" ||
+    (geom === "line" && stat === "bin")
+  ) {
+    errors.push({
+      code: "computed-y-mapped",
+      path: `${layerPath}/aes/y`,
+      message: `The ${geom} geom computes y with the ${stat} stat, so aes.y must not map data. Use geom "col" for pre-computed heights, or unset y with null.`,
+      fix: {
+        description: 'Switch the layer to geom "col" (identity stat) to draw mapped y values.',
+        example: { geom: "col" },
+      },
+    });
+  }
+
+  if (geom === "density") {
+    errors.push({
+      code: "computed-y-mapped",
+      path: `${layerPath}/aes/y`,
+      message:
+        "The density geom computes y with the density stat, so aes.y must not map data. Map only x, or unset y with null.",
+      fix: {
+        description: "Remove the y mapping (or unset an inherited one with null).",
+        example: { geom: "density", aes: { y: null } },
+      },
+    });
+  }
+
+  if (geom === "function" || stat === "function") {
+    errors.push({
+      code: "computed-y-mapped",
+      path: `${layerPath}/aes/y`,
+      message:
+        "The function geom/stat computes y from the named function, so aes.y must not map data. Unset y with null.",
+      fix: {
+        description: "Remove the y mapping (or unset an inherited one with null).",
+        example: { geom: "function", aes: { y: null }, params: { fun: "dnorm", xlim: [-3, 3] } },
+      },
+    });
+  }
+
+  if (geom === "dotplot" || stat === "bindot") {
+    errors.push({
+      code: "computed-y-mapped",
+      path: `${layerPath}/aes/y`,
+      message:
+        "The dotplot geom computes y stack positions with the bindot stat, so aes.y must not map data. Map only x, or unset y with null.",
+      fix: {
+        description: "Remove the y mapping (or unset an inherited one with null).",
+        example: { geom: "dotplot", aes: { y: null } },
+      },
+    });
+  }
+
+  if (geom === "line" && stat === "ecdf") {
+    errors.push({
+      code: "computed-y-mapped",
+      path: `${layerPath}/aes/y`,
+      message:
+        'The ecdf stat computes y (cumulative proportion), so aes.y must not map data. Map only x, or use y: { stat: "ecdf" }.',
+      fix: {
+        description: 'Remove the y mapping (or set y: { stat: "ecdf" }).',
+        example: { geom: "line", stat: "ecdf", aes: { y: null } },
+      },
+    });
+  }
+
+  return errors;
+}

package/src/validate-structure-layer-ribbon.ts

@@ -0,0 +1,61 @@
+/**
+ * Ribbon geom structural form checks (orientation contracts).
+ * Orchestrated by validate-structure-layers.ts.
+ */
+import type { SpecError } from "./errors.js";
+import type { ChannelName } from "./schema.js";
+import { isRecord, pushMissingChannel } from "./validate-structure-layer-shared.js";
+
+export function ribbonStructuralErrors(
+  layer: Record<string, unknown>,
+  layerPath: string,
+  mapped: (channel: ChannelName) => unknown,
+): SpecError[] {
+  const errors: SpecError[] = [];
+  const params = isRecord(layer["params"]) ? layer["params"] : {};
+  const pinned =
+    params["orientation"] === "x" || params["orientation"] === "y" ? params["orientation"] : null;
+  const xContract =
+    mapped("x") !== undefined && mapped("ymin") !== undefined && mapped("ymax") !== undefined;
+  const yContract =
+    mapped("y") !== undefined && mapped("xmin") !== undefined && mapped("xmax") !== undefined;
+
+  if (pinned === null && xContract && yContract) {
+    errors.push({
+      code: "ribbon-orientation-ambiguous",
+      path: `${layerPath}/params/orientation`,
+      message:
+        'This ribbon layer maps both x-orientation (x+ymin+ymax) and y-orientation (y+xmin+xmax) contracts. Set params.orientation to "x" or "y".',
+      fix: {
+        description: "Pin orientation explicitly.",
+        example: { params: { orientation: "x" } },
+      },
+    });
+    return errors;
+  }
+
+  const orientation: "x" | "y" | null =
+    pinned === "x" || pinned === "y" ? pinned : xContract ? "x" : yContract ? "y" : null;
+
+  const usesYContract =
+    orientation === "y" ||
+    (orientation === null &&
+      [mapped("y"), mapped("xmin"), mapped("xmax")].some((value) => value !== undefined));
+  const needed: ChannelName[] = usesYContract ? ["y", "xmin", "xmax"] : ["x", "ymin", "ymax"];
+
+  for (const channel of needed) {
+    if (mapped(channel) !== undefined) continue;
+    const suffix = ribbonContractSuffix(orientation);
+    pushMissingChannel(
+      errors,
+      layerPath,
+      channel,
+      `The ribbon geom ${suffix} requires a "${channel}" channel; map it in the layer's aes or the plot-level aes.`,
+    );
+  }
+  return errors;
+}
+
+function ribbonContractSuffix(orientation: "x" | "y" | null): string {
+  return orientation === null ? "for its interval contract" : `with orientation "${orientation}"`;
+}