@ggts-sh/spec 0.43.0

package/src/validate-map-errors.ts

@@ -0,0 +1,126 @@
+/**
+ * TypeBox 1.x validation errors → agent SpecError mapping (tier-1).
+ *
+ * TypeBox 1.x (`typebox`) reports JSON-Schema-style errors (`keyword`,
+ * `instancePath`, `params`) rather than 0.x `ValueErrorType` + embedded
+ * schema/value. Discriminator-aware union classification (channel forms,
+ * data refs, const enums) is reconstructed from keywords + schema lookup
+ * against the Cyclic root being validated.
+ *
+ * Schema / path inspection: validate-schema-walk.ts.
+ * Channel/data form classification: validate-map-forms.ts.
+ * Union path mapping: validate-map-path-unions.ts.
+ * Keyword path mapping: validate-map-path-keywords.ts.
+ * Used only by validate() — not part of the package public surface.
+ */
+import type { TLocalizedValidationError } from "typebox/error";
+
+import type { SpecError } from "./errors.js";
+import { didYouMean } from "./errors.js";
+import { KNOWN_GEOMS } from "./schema-catalog.js";
+import { lastSegment, pointerGet } from "./validate-schema-walk.js";
+import { mapKeywordPathGroup } from "./validate-map-path-keywords.js";
+import { mapUnionPathGroup } from "./validate-map-path-unions.js";
+
+export interface MapErrorsContext {
+  /** Schema root passed to Value.Errors (Cyclic `$defs`+`$ref`). */
+  schema: unknown;
+  /** Value that was validated (for reading failing values via instancePath). */
+  value: unknown;
+  /** Path prefix prepended to each instancePath (e.g. `/layers/0`). */
+  pathPrefix: string;
+}
+
+/**
+ * Map a batch of TypeBox 1.x validation errors into agent SpecErrors.
+ * Groups const/anyOf noise so enum and channel unions surface as one error.
+ */
+export function mapValueErrors(
+  rawErrors: readonly TLocalizedValidationError[],
+  ctx: MapErrorsContext,
+): SpecError[] {
+  if (rawErrors.length === 0) return [];
+
+  // Group by instancePath so multi-const anyOf enums collapse.
+  const byPath = new Map<string, TLocalizedValidationError[]>();
+  for (const err of rawErrors) {
+    const list = byPath.get(err.instancePath) ?? [];
+    list.push(err);
+    byPath.set(err.instancePath, list);
+  }
+
+  const out: SpecError[] = [];
+  for (const [instancePath, group] of byPath) {
+    out.push(...mapPathGroup(instancePath, group, ctx));
+  }
+  return out;
+}
+
+function mapPathGroup(
+  instancePath: string,
+  group: readonly TLocalizedValidationError[],
+  ctx: MapErrorsContext,
+): SpecError[] {
+  const path = ctx.pathPrefix + instancePath;
+  const key = lastSegment(instancePath);
+  const valueAtPath = pointerGet(ctx.value, instancePath);
+
+  if (
+    group.some((error) => error.keyword === "pattern") &&
+    /^\/scales\/(?:color|fill)\/range\/\d+$/.test(path) &&
+    typeof valueAtPath === "string"
+  ) {
+    return [
+      {
+        code: "scale-range-color",
+        path,
+        message: `The color stop "${valueAtPath}" is not a supported hex color.`,
+        fix: {
+          description: "Use #rgb or #rrggbb syntax for custom color ranges.",
+          example: "#ff0000",
+        },
+      },
+    ];
+  }
+
+  const union = mapUnionPathGroup(instancePath, group, ctx, path, key, valueAtPath);
+  if (union.status === "done") return union.errors;
+
+  return mapKeywordPathGroup(
+    instancePath,
+    group,
+    ctx,
+    path,
+    key,
+    valueAtPath,
+    union.activeFormKeys,
+  );
+}
+
+export function unknownGeomError(geom: unknown, layerPath: string): SpecError {
+  const allowed = [...KNOWN_GEOMS];
+  if (typeof geom !== "string") {
+    return {
+      code: "missing-geom",
+      path: `${layerPath}/geom`,
+      message: `Every layer needs a "geom" discriminator. Allowed geoms: ${allowed.map((g) => `"${g}"`).join(", ")}.`,
+      allowed,
+      fix: {
+        description: "Add a geom to the layer.",
+        example: { geom: "point" },
+      },
+    };
+  }
+  const suggestion = didYouMean(geom, allowed);
+  return {
+    code: "unknown-geom",
+    path: `${layerPath}/geom`,
+    message:
+      `Unknown geom "${geom}". Allowed geoms: ${allowed.map((g) => `"${g}"`).join(", ")}.` +
+      (suggestion === undefined ? "" : ` Did you mean "${suggestion}"?`),
+    allowed,
+    ...(suggestion !== undefined && {
+      fix: { description: `Set geom to "${suggestion}".`, example: { geom: suggestion } },
+    }),
+  };
+}

package/src/validate-map-forms.ts

@@ -0,0 +1,148 @@
+/**
+ * Channel and DataRef form classification for TypeBox 1.x error mapping.
+ * Path/schema walk: validate-schema-walk.ts. SpecError mapping: validate-map-errors.ts.
+ */
+import type { TLocalizedValidationError } from "typebox/error";
+
+import { CHANNELS } from "./schema-catalog.js";
+import { isRecord, pathSegments, type UnionMemberInfo } from "./validate-schema-walk.js";
+
+export const CHANNEL_FIX_EXAMPLE = { field: "column_name" };
+
+/**
+ * Channel names that live under aes (plot- or layer-level).
+ * Derived from CHANNELS so path classification cannot drift behind the catalog (#1078).
+ */
+const AES_CHANNEL_KEYS = new Set<string>(CHANNELS);
+
+/** True only for the channel node itself (`…/aes/<channel>`), not nested paths. */
+export function isChannelPath(path: string): boolean {
+  const segs = pathSegments(path);
+  if (segs.length < 2) return false;
+  const i = segs.length - 2;
+  return segs[i] === "aes" && AES_CHANNEL_KEYS.has(segs[i + 1]!);
+}
+
+/**
+ * DataRef / InlineData union roots only:
+ * `/data`, `/datasets/<name>`, or `/layers/<n>/data`.
+ * Nested paths under a data container must keep their own diagnostics.
+ */
+export function isDataUnionPath(path: string): boolean {
+  const segs = pathSegments(path);
+  if (segs.length === 1 && segs[0] === "data") return true;
+  if (segs.length === 2 && segs[0] === "datasets") return true;
+  // /layers/<index>/data
+  if (
+    segs.length === 3 &&
+    segs[0] === "layers" &&
+    /^\d+$/.test(segs[1] ?? "") &&
+    segs[2] === "data"
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/** Canonical channel object form (or null); bare strings are handled separately. */
+export function looksLikeChannelForm(v: unknown): boolean {
+  if (v === null) return true;
+  if (!isRecord(v)) return false;
+  return "field" in v || "value" in v || "stat" in v;
+}
+
+/** Already a data container shape — do not suggest re-wrapping as `{ values: [...] }`. */
+export function looksLikeDataContainer(v: unknown): boolean {
+  if (!isRecord(v)) return false;
+  return "values" in v || "columns" in v || "name" in v;
+}
+
+export function isScalarValue(v: unknown): boolean {
+  return v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+}
+
+/** Exclusive channel form discriminators (exactly one allowed per channel). */
+const CHANNEL_DISCRIMINATORS = ["field", "value", "stat"] as const;
+/** Exclusive data form discriminators (exactly one allowed per DataRef). */
+const DATA_DISCRIMINATORS = ["values", "columns", "name"] as const;
+
+/**
+ * True when an additionalProperties failure lists a key that is *not* in
+ * `ignoreKeys`. Used to ignore competing-branch noise (e.g. Columns rejecting
+ * `values`) while still surfacing typos and form-illegal keys.
+ */
+export function additionalPropertyNames(
+  group: readonly TLocalizedValidationError[],
+  ignoreKeys: ReadonlySet<string> = new Set(),
+): string[] {
+  const names = new Set<string>();
+  for (const error of group) {
+    if (error.keyword !== "additionalProperties") continue;
+    const listed = Array.isArray(error.params.additionalProperties)
+      ? error.params.additionalProperties
+      : [];
+    for (const key of listed) {
+      if (!ignoreKeys.has(key)) names.add(key);
+    }
+  }
+  return [...names];
+}
+
+export function hasActionableAddlNoise(
+  group: readonly TLocalizedValidationError[],
+  ignoreKeys: ReadonlySet<string>,
+): boolean {
+  return additionalPropertyNames(group, ignoreKeys).length > 0;
+}
+
+export function channelDiscriminatorKeys(v: Record<string, unknown>): string[] {
+  return CHANNEL_DISCRIMINATORS.filter((k) => k in v);
+}
+
+export function dataDiscriminatorKeys(
+  v: Record<string, unknown>,
+  allowed: readonly (typeof DATA_DISCRIMINATORS)[number][] = DATA_DISCRIMINATORS,
+): string[] {
+  return allowed.filter((k) => k in v);
+}
+
+export function dataDiscriminatorsForUnion(
+  members: UnionMemberInfo,
+  path: string,
+): readonly (typeof DATA_DISCRIMINATORS)[number][] {
+  const allowed: (typeof DATA_DISCRIMINATORS)[number][] = [];
+  if (members.refs.some((ref) => ref.endsWith("DataValues"))) allowed.push("values");
+  if (members.refs.some((ref) => ref.endsWith("DataColumns"))) allowed.push("columns");
+  if (members.refs.some((ref) => ref.endsWith("DataName"))) allowed.push("name");
+  if (allowed.length > 0) return allowed;
+  return pathSegments(path)[0] === "datasets" ? ["values", "columns"] : DATA_DISCRIMINATORS;
+}
+
+/**
+ * Keys legal on the single present channel form, or null when forms are mixed
+ * / absent. FieldRef = {field}; ValueRef = {value, scale?}; StatRef = {stat}.
+ */
+export function allowedKeysForPresentChannelForm(v: Record<string, unknown>): Set<string> | null {
+  const discs = channelDiscriminatorKeys(v);
+  if (discs.length !== 1) return null;
+  switch (discs[0]) {
+    case "field":
+      return new Set(["field"]);
+    case "value":
+      return new Set(["value", "scale"]);
+    case "stat":
+      return new Set(["stat"]);
+    default:
+      return null;
+  }
+}
+
+/** Keys legal on the single present data form, or null when forms are mixed. */
+export function allowedKeysForPresentDataForm(
+  v: Record<string, unknown>,
+  allowedDiscriminators: readonly (typeof DATA_DISCRIMINATORS)[number][],
+): Set<string> | null {
+  const discs = dataDiscriminatorKeys(v, allowedDiscriminators);
+  if (discs.length !== 1) return null;
+  return new Set([discs[0]!]);
+}

package/src/validate-map-path-keywords.ts

@@ -0,0 +1,129 @@
+/**
+ * Keyword path mapping for TypeBox 1.x errors: additionalProperties, required,
+ * numeric range, and default type normalization.
+ * Union classification: validate-map-path-unions.ts. Orchestrator: validate-map-errors.ts.
+ */
+import type { TLocalizedValidationError } from "typebox/error";
+
+import type { SpecError } from "./errors.js";
+import { didYouMean } from "./errors.js";
+import {
+  additionalPropertiesIsClosed,
+  numberBounds,
+  objectPropertyNames,
+  pointerGet,
+  schemaAtInstancePath,
+  schemaAtSchemaPath,
+} from "./validate-schema-walk.js";
+import { additionalPropertyNames } from "./validate-map-forms.js";
+import type { MapErrorsContext } from "./validate-map-errors.js";
+
+/** Map remaining keywords after union classification (or when no anyOf/const). */
+export function mapKeywordPathGroup(
+  instancePath: string,
+  group: readonly TLocalizedValidationError[],
+  ctx: MapErrorsContext,
+  path: string,
+  key: string,
+  valueAtPath: unknown,
+  activeFormKeys: ReadonlySet<string> | null,
+): SpecError[] {
+  // additionalProperties: closed objects → unexpected keys; schema-valued
+  // additionalProperties (records / free-form rows) → value type failures.
+  const addl = group.find((e) => e.keyword === "additionalProperties");
+  if (addl !== undefined) {
+    const listed = additionalPropertyNames(group, activeFormKeys ?? new Set());
+    const objectSchema =
+      (typeof addl.schemaPath === "string"
+        ? schemaAtSchemaPath(ctx.schema, instancePath, addl.schemaPath)
+        : null) ?? schemaAtInstancePath(ctx.schema, instancePath);
+    if (!additionalPropertiesIsClosed(objectSchema)) {
+      return listed.map((prop) => {
+        const propPath = `${path}/${prop}`;
+        const propValue = pointerGet(ctx.value, `${instancePath}/${prop}`);
+        return {
+          code: "invalid-type" as const,
+          path: propPath,
+          message: `Invalid value for "${prop}" (got ${JSON.stringify(propValue)}).`,
+        };
+      });
+    }
+    const properties =
+      activeFormKeys === null ? objectPropertyNames(objectSchema) : [...activeFormKeys];
+    return listed.map((prop) => {
+      const propPath = `${path}/${prop}`;
+      const suggestion = didYouMean(prop, properties);
+      return {
+        code: "unexpected-property" as const,
+        path: propPath,
+        message:
+          `Unknown property "${prop}".` +
+          (suggestion === undefined ? "" : ` Did you mean "${suggestion}"?`),
+        allowed: properties,
+        ...(suggestion !== undefined && {
+          fix: { description: `Rename "${prop}" to "${suggestion}".` },
+        }),
+      };
+    });
+  }
+
+  // required: may list several missing keys.
+  const req = group.find((e) => e.keyword === "required");
+  if (req !== undefined) {
+    const missing = Array.isArray(req.params.requiredProperties)
+      ? req.params.requiredProperties
+      : [];
+    return missing.map((prop) => ({
+      code: "missing-property" as const,
+      path: `${path}/${prop}`,
+      message: `Missing required property "${prop}".`,
+    }));
+  }
+
+  // numeric range — use schema bounds when available for full min+max message.
+  const rangeErr = group.find((e) =>
+    ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"].includes(e.keyword),
+  );
+  if (rangeErr !== undefined) {
+    const propSchema =
+      schemaAtInstancePath(ctx.schema, instancePath) ??
+      schemaAtSchemaPath(ctx.schema, instancePath, rangeErr.schemaPath);
+    let bounds = numberBounds(propSchema);
+    if (bounds.length === 0) {
+      const limit = (rangeErr.params as { limit?: number }).limit;
+      const comparison = (rangeErr.params as { comparison?: string }).comparison;
+      if (typeof limit === "number" && typeof comparison === "string") {
+        bounds = [`${comparison} ${limit}`];
+      }
+    }
+    return [
+      {
+        code: "value-out-of-range",
+        path,
+        message: `Value ${JSON.stringify(valueAtPath)} for "${key}" is out of range (must be ${bounds.join(" and ")}).`,
+        fix: { description: `Set "${key}" to a number ${bounds.join(" and ")}.` },
+      },
+    ];
+  }
+
+  // Lone const (Literal) without anyOf group — handled in union module when
+  // constErrs non-empty; fall through to default for remaining keywords (type, etc.).
+
+  // Normalize 1.x "must be X" wording toward the catalog's "Expected X" form.
+  const first = group[0]!;
+  let message = first.message;
+  if (first.keyword === "type") {
+    const t = (first.params as { type?: string | string[] }).type;
+    const expected = Array.isArray(t) ? t.join("|") : t;
+    if (typeof expected === "string") {
+      message = `Expected ${expected}`;
+    }
+  }
+  return [
+    {
+      code: "invalid-type",
+      path,
+      message: `${message}${path === "" ? "" : ` at "${key}"`} (got ${JSON.stringify(valueAtPath)}).`,
+    },
+  ];
+}

package/src/validate-map-path-unions.ts

@@ -0,0 +1,281 @@
+/**
+ * anyOf/const union path mapping for TypeBox 1.x errors (channel forms, data
+ * refs, enums). Keyword handlers: validate-map-path-keywords.ts.
+ * Orchestrator: validate-map-errors.ts.
+ *
+ * Result contract:
+ *  - `{ status: "done", errors }` — including `errors: []` meaning "suppress
+ *    noisy union diagnostics; a nested path owns the real error"
+ *  - `{ status: "continue", activeFormKeys }` — fall through to keyword handlers
+ *    (activeFormKeys null when no near-canonical form keyed the fall-through)
+ */
+import type { TLocalizedValidationError } from "typebox/error";
+
+import type { SpecError } from "./errors.js";
+import { didYouMean } from "./errors.js";
+import {
+  isRecord,
+  schemaAtInstancePath,
+  schemaAtSchemaPath,
+  unionMembers,
+} from "./validate-schema-walk.js";
+import {
+  allowedKeysForPresentChannelForm,
+  allowedKeysForPresentDataForm,
+  channelDiscriminatorKeys,
+  CHANNEL_FIX_EXAMPLE,
+  dataDiscriminatorKeys,
+  dataDiscriminatorsForUnion,
+  hasActionableAddlNoise,
+  isChannelPath,
+  isDataUnionPath,
+  isScalarValue,
+  looksLikeChannelForm,
+  looksLikeDataContainer,
+} from "./validate-map-forms.js";
+import type { MapErrorsContext } from "./validate-map-errors.js";
+
+export type UnionPathResult =
+  | { status: "done"; errors: SpecError[] }
+  | { status: "continue"; activeFormKeys: ReadonlySet<string> | null };
+
+/**
+ * Classify anyOf/const group noise. When neither anyOf nor const is present,
+ * returns continue with null form keys so keyword handlers still run.
+ */
+export function mapUnionPathGroup(
+  instancePath: string,
+  group: readonly TLocalizedValidationError[],
+  ctx: MapErrorsContext,
+  path: string,
+  key: string,
+  valueAtPath: unknown,
+): UnionPathResult {
+  const anyOfErr = group.find((e) => e.keyword === "anyOf");
+  const constErrs = group.filter((e) => e.keyword === "const");
+
+  if (anyOfErr === undefined && constErrs.length === 0) {
+    return { status: "continue", activeFormKeys: null };
+  }
+
+  // Object-branch noise in mixed unions (e.g. ThemeName | ThemeSpec): prefer
+  // required / additionalProperties over const-branch enum synthesis.
+  const hasObjectBranchNoise =
+    isRecord(valueAtPath) &&
+    group.some((e) => e.keyword === "additionalProperties" || e.keyword === "required");
+
+  // anyOf / const unions FIRST: 1.x fans out branch failures (required +
+  // additionalProperties + anyOf) for object unions. Prefer the anyOf signal
+  // so DataRef / ChannelValue surface catalog codes, not branch noise — except
+  // when the instance already matches a near-canonical form (nested paths own
+  // the real diagnostic) or an object branch reported concrete property noise.
+  const unionSchema =
+    (anyOfErr === undefined
+      ? null
+      : schemaAtSchemaPath(ctx.schema, instancePath, anyOfErr.schemaPath)) ??
+    schemaAtInstancePath(ctx.schema, instancePath);
+  const members = unionMembers(unionSchema);
+
+  const isChannel =
+    members.refs.includes("FieldRef") ||
+    members.refs.some((r) => r.endsWith("FieldRef")) ||
+    isChannelPath(path);
+
+  if (isChannel && !members.allConst) {
+    return mapChannelUnion(group, path, key, valueAtPath);
+  }
+
+  const isDataUnion =
+    members.refs.includes("DataValues") ||
+    members.refs.some((r) => r.includes("DataValues")) ||
+    (isDataUnionPath(path) && anyOfErr !== undefined);
+
+  if (isDataUnion) {
+    return mapDataUnion(group, members, path, valueAtPath);
+  }
+
+  return mapEnumUnion(anyOfErr, constErrs, members, hasObjectBranchNoise, valueAtPath, path, key);
+}
+
+function mapEnumUnion(
+  anyOfErr: TLocalizedValidationError | undefined,
+  constErrs: readonly TLocalizedValidationError[],
+  members: ReturnType<typeof unionMembers>,
+  hasObjectBranchNoise: boolean,
+  valueAtPath: unknown,
+  path: string,
+  key: string,
+): UnionPathResult {
+  let allowed: string[] = [];
+  if (constErrs.length > 0) {
+    allowed = constErrs
+      .map((e) => (e.params as { allowedValue?: unknown }).allowedValue)
+      .filter((v) => v !== undefined)
+      .map(String);
+  }
+  if (allowed.length === 0 && members.allConst && members.consts.length > 0) {
+    allowed = members.consts;
+  }
+  // Only promote const branch noise when the value could be an enum member.
+  // Mixed enum|object unions (theme) must not turn ThemeSpec property errors
+  // into "pick a theme name".
+  if (
+    allowed.length > 0 &&
+    (members.allConst || isScalarValue(valueAtPath)) &&
+    !hasObjectBranchNoise
+  ) {
+    if (allowed.length === 1 && constErrs.length <= 1 && anyOfErr === undefined) {
+      return {
+        status: "done",
+        errors: [
+          {
+            code: "invalid-enum-value",
+            path,
+            message: `Invalid value ${JSON.stringify(valueAtPath)} for "${key}"; the only supported value is ${allowed.map((a) => `"${a}"`).join(", ")}.`,
+            allowed,
+          },
+        ],
+      };
+    }
+    const suggestion =
+      typeof valueAtPath === "string" ? didYouMean(valueAtPath, allowed) : undefined;
+    return {
+      status: "done",
+      errors: [
+        {
+          code: "invalid-enum-value",
+          path,
+          message:
+            `Invalid value ${JSON.stringify(valueAtPath)} for "${key}"; allowed: ${allowed.map((c) => `"${c}"`).join(", ")}.` +
+            (suggestion === undefined ? "" : ` Did you mean "${suggestion}"?`),
+          allowed,
+          ...(suggestion !== undefined && {
+            fix: { description: `Set "${key}" to "${suggestion}".` },
+          }),
+        },
+      ],
+    };
+  }
+
+  if (anyOfErr !== undefined && !hasObjectBranchNoise) {
+    return {
+      status: "done",
+      errors: [
+        {
+          code: "invalid-type",
+          path,
+          message: `${anyOfErr.message} at "${key}".`,
+        },
+      ],
+    };
+  }
+  return { status: "continue", activeFormKeys: null };
+}
+
+function mapChannelUnion(
+  group: readonly TLocalizedValidationError[],
+  path: string,
+  key: string,
+  valueAtPath: unknown,
+): UnionPathResult {
+  if (isRecord(valueAtPath) && looksLikeChannelForm(valueAtPath)) {
+    const discs = channelDiscriminatorKeys(valueAtPath);
+    if (discs.length > 1) {
+      return {
+        status: "done",
+        errors: [
+          {
+            code: "invalid-channel-value",
+            path,
+            message: `Channel "${key}" mixes forms (${discs.map((disc) => `"${disc}"`).join(" and ")}); use exactly one of {"field": ...}, {"value": ...}, or {"stat": ...}.`,
+            fix: {
+              description: `Pick a single channel form for "${key}".`,
+              example: CHANNEL_FIX_EXAMPLE,
+            },
+          },
+        ],
+      };
+    }
+    const formKeys = allowedKeysForPresentChannelForm(valueAtPath);
+    if (formKeys !== null && hasActionableAddlNoise(group, formKeys)) {
+      return { status: "continue", activeFormKeys: formKeys };
+    }
+    return { status: "done", errors: [] };
+  }
+  const bareString = typeof valueAtPath === "string";
+  return {
+    status: "done",
+    errors: [
+      {
+        code: "invalid-channel-value",
+        path,
+        message: bareString
+          ? `Channel "${key}" is the bare string ${JSON.stringify(valueAtPath)}; portable specs require the canonical form {"field": ${JSON.stringify(valueAtPath)}}.`
+          : `Channel "${key}" must be {"field": ...}, {"value": ...}, {"stat": ...}, or null.`,
+        fix: {
+          description: `Use a canonical channel form, e.g. {"field": "column_name"} to map "${key}" to a data column.`,
+          example: bareString ? { field: valueAtPath } : CHANNEL_FIX_EXAMPLE,
+        },
+      },
+    ],
+  };
+}
+
+function mapDataUnion(
+  group: readonly TLocalizedValidationError[],
+  members: ReturnType<typeof unionMembers>,
+  path: string,
+  valueAtPath: unknown,
+): UnionPathResult {
+  const allowed = dataDiscriminatorsForUnion(members, path);
+  const forms = allowed.map((discriminator) => {
+    if (discriminator === "values") return '{"values": [...rows]}';
+    if (discriminator === "columns") return '{"columns": {...arrays}}';
+    return '{"name": "dataset"}';
+  });
+  const formsMessage =
+    forms.length === 2
+      ? `${forms[0]} or ${forms[1]}`
+      : `${forms.slice(0, -1).join(", ")}, or ${forms.at(-1)}`;
+  if (isRecord(valueAtPath) && looksLikeDataContainer(valueAtPath)) {
+    const discs = dataDiscriminatorKeys(valueAtPath, allowed);
+    if (discs.length > 1) {
+      return {
+        status: "done",
+        errors: [
+          {
+            code: "invalid-data",
+            path,
+            message: `Data mixes forms (${discs.map((disc) => `"${disc}"`).join(" and ")}); use exactly one of ${formsMessage}.`,
+            allowed: [...allowed],
+            fix: {
+              description: "Pick a single data form.",
+              example: { values: [{ x: 1, y: 2 }] },
+            },
+          },
+        ],
+      };
+    }
+    const presentFormKeys = allowedKeysForPresentDataForm(valueAtPath, allowed);
+    const formKeys = presentFormKeys ?? new Set(allowed);
+    if (hasActionableAddlNoise(group, formKeys)) {
+      return { status: "continue", activeFormKeys: formKeys };
+    }
+    return { status: "done", errors: [] };
+  }
+  return {
+    status: "done",
+    errors: [
+      {
+        code: "invalid-data",
+        path,
+        message: `Data must be one of ${formsMessage}.`,
+        allowed: [...allowed],
+        fix: {
+          description: 'Wrap inline rows as {"values": [...]}.',
+          example: { values: [{ x: 1, y: 2 }] },
+        },
+      },
+    ],
+  };
+}