@metaobjectsdev/metadata 0.5.0-rc.1

package/src/core/query/query-constants.ts

@@ -0,0 +1,66 @@
+// Query concern constants — filter operators, sort order values.
+//
+// NOTE: `query` is NOT a metamodel node type — it has no subtype, schema, or
+// accessor. It's a cross-cutting vocabulary grouping for query/filter helpers
+// consumed by both core/field (@filterable/@sortable) and presentation/layout
+// (dataGrid @defaultSortOrder). Co-located here as the most foundational shared
+// home; intentional, not an incomplete migration.
+
+// ---------------------------------------------------------------------------
+// Filter operators (Project D) — shared source of truth across server +
+// codegen. Each subtype declares which operators are legal for fields of that
+// type. Server allowlist generation + TS type generation + codegen-time grid
+// validation all import from here.
+// ---------------------------------------------------------------------------
+
+// Individual operator constants — used by the parse-time desugar in
+// parser-core.ts. Must stay in sync with FILTER_OPS below.
+export const FILTER_OP_EQ      = "eq";
+export const FILTER_OP_NE      = "ne";
+export const FILTER_OP_GT      = "gt";
+export const FILTER_OP_GTE     = "gte";
+export const FILTER_OP_LT      = "lt";
+export const FILTER_OP_LTE     = "lte";
+export const FILTER_OP_IN      = "in";
+export const FILTER_OP_LIKE    = "like";
+export const FILTER_OP_IS_NULL = "isNull";
+
+// Composition-key constants — used by desugarFilterObject in meta-attr-filter.ts.
+export const FILTER_COMPOSE_OR = "or";
+export const FILTER_COMPOSE_AND = "and";
+
+export const FILTER_OPS = [
+  FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE,
+  FILTER_OP_IN, FILTER_OP_LIKE, FILTER_OP_IS_NULL,
+] as const;
+export type FilterOp = (typeof FILTER_OPS)[number];
+
+export const OPS_BY_SUBTYPE: Readonly<Record<string, readonly FilterOp[]>> = {
+  string:    [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_IN, FILTER_OP_LIKE, FILTER_OP_IS_NULL],
+  int:       [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  short:     [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  byte:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  long:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  double:    [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  float:     [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  decimal:   [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  boolean:   [FILTER_OP_EQ, FILTER_OP_IS_NULL],
+  date:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  time:      [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+  timestamp: [FILTER_OP_EQ, FILTER_OP_NE, FILTER_OP_GT, FILTER_OP_GTE, FILTER_OP_LT, FILTER_OP_LTE, FILTER_OP_IN, FILTER_OP_IS_NULL],
+} as const;
+
+export function opsForSubType(subType: string): readonly FilterOp[] {
+  return OPS_BY_SUBTYPE[subType] ?? [];
+}
+
+// ---------------------------------------------------------------------------
+// Sort order values (used by @sortableDefaultOrder on fields and
+// @defaultSortOrder on dataGrid layouts)
+// ---------------------------------------------------------------------------
+
+export const SORT_ORDER_ASC  = "asc";
+export const SORT_ORDER_DESC = "desc";
+
+export const SORT_ORDER_VALUES = [SORT_ORDER_ASC, SORT_ORDER_DESC] as const;
+export type SortOrderValue = (typeof SORT_ORDER_VALUES)[number];

package/src/core/relationship/find-reference.ts

@@ -0,0 +1,44 @@
+// Cross-entity reference lookup — anchored to identity.reference declarations.
+//
+// Given a relationship-style query "is there a reference between A and B?",
+// walk A's and B's identity.reference children to find the side that physically
+// holds the reference. This is the single source of truth for FK direction
+// across projection codegen, Drizzle schema emit, relations() blocks, and
+// migration schema comparison.
+
+import type { MetaObject } from "../object/meta-object.js";
+import type { MetaReferenceIdentity } from "../identity/meta-identity.js";
+import { stripPackage } from "../../naming.js";
+
+export interface ReferenceLookup {
+  /** The entity whose identity.reference points at `other`. */
+  readonly holder: MetaObject;
+  /** The other side of the reference. */
+  readonly other: MetaObject;
+  /** The matching identity.reference declaration on `holder`. */
+  readonly referenceIdentity: MetaReferenceIdentity;
+}
+
+/**
+ * Find an identity.reference on either `a` or `b` whose @references targets the
+ * other side. Returns undefined if neither side declares one.
+ *
+ * Comparison is package-insensitive: `@references` may be a bare entity name
+ * ("User") or a fully-qualified one ("pkg::User"); both match `other.name`.
+ *
+ * If both sides declare references targeting each other (rare, but legal for
+ * mutual 1:1), returns the first found, walking `a` first.
+ */
+export function findReferenceBetween(
+  a: MetaObject,
+  b: MetaObject,
+): ReferenceLookup | undefined {
+  for (const [holder, other] of [[a, b], [b, a]] as const) {
+    for (const ref of holder.referenceIdentities()) {
+      if (stripPackage(ref.targetEntity) === other.name) {
+        return { holder, other, referenceIdentity: ref };
+      }
+    }
+  }
+  return undefined;
+}

package/src/core/relationship/meta-relationship.ts

@@ -0,0 +1,36 @@
+// MetaRelationship — concrete node class for type=relationship nodes.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  RELATIONSHIP_ATTR_CARDINALITY,
+  RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_JOIN_ENTITY,
+  RELATIONSHIP_ATTR_JOIN_FIELDS,
+} from "./relationship-constants.js";
+
+export class MetaRelationship extends MetaData {
+  get cardinality(): string | undefined {
+    const v = this.ownAttr(RELATIONSHIP_ATTR_CARDINALITY);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** FQN of the target object (e.g., "acme::vehicle::Car"). */
+  get objectRef(): string | undefined {
+    const v = this.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** Join-table entity name for N:M relationships. */
+  get joinEntity(): string | undefined {
+    const v = this.ownAttr(RELATIONSHIP_ATTR_JOIN_ENTITY);
+    return typeof v === "string" ? v : undefined;
+  }
+
+  /** Join-table column names for N:M relationships. */
+  get joinFields(): string[] {
+    const f = this.ownAttr(RELATIONSHIP_ATTR_JOIN_FIELDS);
+    return Array.isArray(f) ? (f as string[]) : [];
+  }
+}

package/src/core/relationship/relationship-constants.ts

@@ -0,0 +1,38 @@
+// Relationship concern constants — subtypes, attr keys, and cardinality values.
+
+import { SUBTYPE_BASE } from "../../shared/base-types.js";
+
+// ---------------------------------------------------------------------------
+// Relationship subtypes (4)
+// ---------------------------------------------------------------------------
+
+export const RELATIONSHIP_SUBTYPE_ASSOCIATION = "association";
+export const RELATIONSHIP_SUBTYPE_AGGREGATION = "aggregation";
+export const RELATIONSHIP_SUBTYPE_COMPOSITION = "composition";
+
+export const RELATIONSHIP_SUBTYPES = [
+  SUBTYPE_BASE,
+  RELATIONSHIP_SUBTYPE_ASSOCIATION,
+  RELATIONSHIP_SUBTYPE_AGGREGATION,
+  RELATIONSHIP_SUBTYPE_COMPOSITION,
+] as const;
+export type RelationshipSubType = (typeof RELATIONSHIP_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Relationship attrs
+// ---------------------------------------------------------------------------
+
+export const RELATIONSHIP_ATTR_CARDINALITY = "cardinality";
+export const RELATIONSHIP_ATTR_OBJECT_REF = "objectRef";
+export const RELATIONSHIP_ATTR_JOIN_ENTITY = "joinEntity";    // N:M cardinality
+export const RELATIONSHIP_ATTR_JOIN_FIELDS = "joinFields";    // N:M cardinality
+
+// ---------------------------------------------------------------------------
+// Relationship cardinality values (for RELATIONSHIP_ATTR_CARDINALITY)
+// ---------------------------------------------------------------------------
+
+export const CARDINALITY_ONE = "one";
+export const CARDINALITY_MANY = "many";
+
+export const CARDINALITY_VALUES = [CARDINALITY_ONE, CARDINALITY_MANY] as const;
+export type CardinalityValue = (typeof CARDINALITY_VALUES)[number];

package/src/core/relationship/relationship-schema.ts

@@ -0,0 +1,49 @@
+// Relationship attribute schemas — attrs common to every relationship subtype.
+// Consumed by registerCoreTypes().
+
+import type { AttrSchema } from "../../registry.js";
+import {
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_STRINGARRAY,
+} from "../attr/attr-constants.js";
+import {
+  RELATIONSHIP_ATTR_CARDINALITY,
+  RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_JOIN_ENTITY,
+  RELATIONSHIP_ATTR_JOIN_FIELDS,
+} from "./relationship-constants.js";
+
+/** Attrs common to every relationship subtype. */
+export const relationshipAttrs: AttrSchema[] = [
+  {
+    name: RELATIONSHIP_ATTR_CARDINALITY,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    // No allowedValues: @cardinality is an open string at the metamodel level
+    // (MetaRelationship.cardinality returns `string | undefined`). The Java
+    // canonical fixtures use composite forms such as "many-to-one"; the
+    // CARDINALITY_VALUES ("one"/"many") constant is a TS codegen convenience,
+    // NOT a closed metamodel enum. A3 must not reject the Java-canonical values.
+    description:
+      "Cardinality of the relationship target (e.g. 'one', 'many', 'many-to-one').",
+  },
+  {
+    name: RELATIONSHIP_ATTR_OBJECT_REF,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description:
+      "Name or fully-qualified name of the target object the relationship points to (e.g. 'Week' or 'acme::vehicle::Car').",
+  },
+  {
+    name: RELATIONSHIP_ATTR_JOIN_ENTITY,
+    valueType: ATTR_SUBTYPE_STRING,
+    required: false,
+    description: "Join-table entity name for N:M relationships.",
+  },
+  {
+    name: RELATIONSHIP_ATTR_JOIN_FIELDS,
+    valueType: ATTR_SUBTYPE_STRINGARRAY,
+    required: false,
+    description: "Join-table column names for N:M relationships.",
+  },
+];

package/src/core/validator/meta-validator.ts

@@ -0,0 +1,62 @@
+// MetaValidator — concrete node class for type=validator nodes.
+// Subtype classes (Required, Length, Regex, Numeric, Array) are co-located.
+//
+// Extends MetaData directly: no model wrapper, no metaOf() indirection.
+
+import { MetaData } from "../../shared/meta-data.js";
+import {
+  VALIDATOR_SUBTYPE_REQUIRED,
+  VALIDATOR_SUBTYPE_LENGTH,
+  VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_ATTR_PATTERN,
+  VALIDATOR_ATTR_MIN,
+  VALIDATOR_ATTR_MAX,
+} from "./validator-constants.js";
+
+export class MetaValidator extends MetaData {
+  /**
+   * Numeric range — shared by length, numeric, and array validators.
+   * (Pattern moves to MetaRegexValidator; required validators have no extra attrs.)
+   */
+  get min(): number | undefined {
+    const v = this.ownAttr(VALIDATOR_ATTR_MIN);
+    return typeof v === "number" ? v : undefined;
+  }
+
+  get max(): number | undefined {
+    const v = this.ownAttr(VALIDATOR_ATTR_MAX);
+    return typeof v === "number" ? v : undefined;
+  }
+
+  isRequired(): boolean {
+    return this.subType === VALIDATOR_SUBTYPE_REQUIRED;
+  }
+
+  isLength(): boolean {
+    return this.subType === VALIDATOR_SUBTYPE_LENGTH;
+  }
+
+  isRegex(): boolean {
+    return this.subType === VALIDATOR_SUBTYPE_REGEX;
+  }
+}
+
+/** Required validator (no extra attrs; subtype class exists for instanceof narrowing). */
+export class MetaRequiredValidator extends MetaValidator {}
+
+/** Length validator: min/max are string/array length bounds. */
+export class MetaLengthValidator extends MetaValidator {}
+
+/** Regex validator: carries the pattern. */
+export class MetaRegexValidator extends MetaValidator {
+  get pattern(): string | undefined {
+    const v = this.ownAttr(VALIDATOR_ATTR_PATTERN);
+    return typeof v === "string" ? v : undefined;
+  }
+}
+
+/** Numeric validator: min/max are value bounds. */
+export class MetaNumericValidator extends MetaValidator {}
+
+/** Array validator: min/max are element-count bounds. */
+export class MetaArrayValidator extends MetaValidator {}

package/src/core/validator/validator-constants.ts

@@ -0,0 +1,31 @@
+// Validator concern constants — subtypes and attr keys for the validator.* type family.
+
+import { SUBTYPE_BASE } from "../../shared/base-types.js";
+
+// ---------------------------------------------------------------------------
+// Validator subtypes (6)
+// ---------------------------------------------------------------------------
+
+export const VALIDATOR_SUBTYPE_REQUIRED = "required";
+export const VALIDATOR_SUBTYPE_LENGTH = "length";
+export const VALIDATOR_SUBTYPE_REGEX = "regex";
+export const VALIDATOR_SUBTYPE_NUMERIC = "numeric";
+export const VALIDATOR_SUBTYPE_ARRAY = "array";
+
+export const VALIDATOR_SUBTYPES = [
+  SUBTYPE_BASE,
+  VALIDATOR_SUBTYPE_REQUIRED,
+  VALIDATOR_SUBTYPE_LENGTH,
+  VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_SUBTYPE_NUMERIC,
+  VALIDATOR_SUBTYPE_ARRAY,
+] as const;
+export type ValidatorSubType = (typeof VALIDATOR_SUBTYPES)[number];
+
+// ---------------------------------------------------------------------------
+// Validator attr keys (used by codegen-ts when reading validator children)
+// ---------------------------------------------------------------------------
+
+export const VALIDATOR_ATTR_PATTERN = "pattern";
+export const VALIDATOR_ATTR_MIN = "min";
+export const VALIDATOR_ATTR_MAX = "max";

package/src/core/validator/validator-schema.ts

@@ -0,0 +1,50 @@
+// Validator attribute schemas — per-subtype attr inventories for validator types.
+// Consumed by registerCoreTypes().
+
+import type { AttrSchema } from "../../registry.js";
+import { ATTR_SUBTYPE_INT, ATTR_SUBTYPE_STRING } from "../attr/attr-constants.js";
+import { SUBTYPE_BASE } from "../../shared/base-types.js";
+import {
+  VALIDATOR_SUBTYPE_REQUIRED,
+  VALIDATOR_SUBTYPE_LENGTH,
+  VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_SUBTYPE_NUMERIC,
+  VALIDATOR_SUBTYPE_ARRAY,
+  VALIDATOR_ATTR_PATTERN,
+  VALIDATOR_ATTR_MIN,
+  VALIDATOR_ATTR_MAX,
+} from "./validator-constants.js";
+
+/** @min / @max shared by length, numeric, array, and the base validator. */
+const minMaxValidatorAttrs: AttrSchema[] = [
+  {
+    name: VALIDATOR_ATTR_MIN,
+    valueType: ATTR_SUBTYPE_INT,
+    required: false,
+    description: "Minimum allowed value (length, numeric value, or array element count depending on the validator subtype).",
+  },
+  {
+    name: VALIDATOR_ATTR_MAX,
+    valueType: ATTR_SUBTYPE_INT,
+    required: false,
+    description: "Maximum allowed value (length, numeric value, or array element count depending on the validator subtype).",
+  },
+];
+
+/** Attrs per validator subtype. Required uses none; regex adds @pattern. */
+export const VALIDATOR_ATTRS_MAP = new Map<string, AttrSchema[]>([
+  [SUBTYPE_BASE, [...minMaxValidatorAttrs]],
+  [VALIDATOR_SUBTYPE_REQUIRED, []],
+  [VALIDATOR_SUBTYPE_LENGTH, [...minMaxValidatorAttrs]],
+  [VALIDATOR_SUBTYPE_REGEX, [
+    ...minMaxValidatorAttrs,
+    {
+      name: VALIDATOR_ATTR_PATTERN,
+      valueType: ATTR_SUBTYPE_STRING,
+      required: false,
+      description: "Regular expression the value must match.",
+    },
+  ]],
+  [VALIDATOR_SUBTYPE_NUMERIC, [...minMaxValidatorAttrs]],
+  [VALIDATOR_SUBTYPE_ARRAY, [...minMaxValidatorAttrs]],
+]);

package/src/core/yaml-desugar.ts

@@ -0,0 +1,145 @@
+// YAML authoring → canonical desugar.
+//
+// desugar() turns the sugared authoring object (from yaml.parse) into the
+// canonical-shaped object that buildTree (parser-core.ts) consumes. It applies
+// the four format-spec sugar rules:
+//   1. Fused key, subType omittable — a bare `type` key resolves to the type's
+//      registry default subType.
+//   2. Scalar-or-map body — a scalar body becomes { name: <scalar> }.
+//   3. Omit empties — absent keys stay absent; the desugar invents nothing.
+//   4. `[]` arrays — a trailing `[]` on the key strips to isArray: true.
+//
+// Pure and total: it never throws. Malformed fragments are collected as error
+// strings and a safe placeholder is substituted so buildTree does not
+// double-report.
+
+import type { TypeRegistry } from "../registry.js";
+import {
+  RESERVED_KEY_CHILDREN,
+  RESERVED_KEY_NAME,
+  RESERVED_KEY_IS_ARRAY,
+  TYPE_SUBTYPE_SEPARATOR,
+} from "../shared/structural.js";
+
+const ARRAY_SUFFIX = "[]";
+
+export interface DesugarResult {
+  /** The canonical-shaped object; `{}` when the document was unusable. */
+  canonical: Record<string, unknown>;
+  /** Collected desugar problems (never thrown). */
+  errors: string[];
+}
+
+/** Desugar a parsed-YAML authoring document into a canonical-shaped object. */
+export function desugar(input: unknown, registry: TypeRegistry): DesugarResult {
+  const errors: string[] = [];
+  const node = desugarNode(input, registry, errors, "<root>");
+  return { canonical: node ?? {}, errors };
+}
+
+// Desugar one node — a single-key mapping { "type.subType": body }.
+// Returns the canonical node object, or undefined if `input` is not a usable
+// node (the caller substitutes a placeholder).
+function desugarNode(
+  input: unknown,
+  registry: TypeRegistry,
+  errors: string[],
+  path: string,
+): Record<string, unknown> | undefined {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    errors.push(`Node at ${path} must be a mapping with one type key`);
+    return undefined;
+  }
+
+  const entries = Object.keys(input as Record<string, unknown>);
+  if (entries.length !== 1) {
+    errors.push(
+      `Node at ${path} must have exactly one type key (found: ${
+        entries.length === 0 ? "none" : entries.join(", ")
+      })`,
+    );
+    return undefined;
+  }
+
+  const rawKey = entries[0]!;
+  const rawBody = (input as Record<string, unknown>)[rawKey];
+
+  // Rule 4: a trailing "[]" on the key → isArray.
+  let key = rawKey;
+  let isArray = false;
+  if (key.endsWith(ARRAY_SUFFIX)) {
+    key = key.slice(0, -ARRAY_SUFFIX.length);
+    isArray = true;
+  }
+
+  // Rule 1: a bare `type` key → the type's registry default subType.
+  const canonicalKey = resolveKey(key, registry, errors, path);
+
+  // Rule 2: a scalar body → { name: <scalar> }.
+  const body = desugarBody(rawBody, errors, path);
+
+  // Rule 4 (cont.): stamp isArray onto the canonical body.
+  if (isArray) body[RESERVED_KEY_IS_ARRAY] = true;
+
+  // Recurse into children.
+  const rawChildren = body[RESERVED_KEY_CHILDREN];
+  if (Array.isArray(rawChildren)) {
+    const children: unknown[] = [];
+    for (let i = 0; i < rawChildren.length; i++) {
+      const childPath = `${path}.${RESERVED_KEY_CHILDREN}[${i}]`;
+      const child = desugarNode(rawChildren[i], registry, errors, childPath);
+      // On a bad child keep an empty-object placeholder so sibling indices
+      // stay stable; the error is already collected.
+      children.push(child ?? {});
+    }
+    body[RESERVED_KEY_CHILDREN] = children;
+  }
+  // A non-array `children` value is left untouched — buildTree reports it.
+
+  return { [canonicalKey]: body };
+}
+
+// Rule 1 — resolve a possibly-bare key to a fused `type.subType` token.
+function resolveKey(
+  key: string,
+  registry: TypeRegistry,
+  errors: string[],
+  path: string,
+): string {
+  if (key.includes(TYPE_SUBTYPE_SEPARATOR)) return key; // already fused
+  const subType = registry.defaultSubTypeOf(key);
+  if (subType === undefined) {
+    errors.push(
+      `Cannot resolve subType for bare type key '${key}' at ${path} — ` +
+        `type '${key}' has no default subType; write the full 'type.subType'`,
+    );
+    return key; // pass through; buildTree reports the unknown type
+  }
+  return `${key}${TYPE_SUBTYPE_SEPARATOR}${subType}`;
+}
+
+// Rule 2 — normalize a node body into a canonical mapping.
+function desugarBody(
+  rawBody: unknown,
+  errors: string[],
+  path: string,
+): Record<string, unknown> {
+  if (
+    typeof rawBody === "string" ||
+    typeof rawBody === "number" ||
+    typeof rawBody === "boolean"
+  ) {
+    return { [RESERVED_KEY_NAME]: rawBody };
+  }
+  if (rawBody === null || rawBody === undefined) {
+    // An empty body (`field.string:` with nothing after) → an empty node.
+    return {};
+  }
+  if (Array.isArray(rawBody)) {
+    errors.push(`Node body at ${path} must be a scalar or mapping, not a list`);
+    return {};
+  }
+  // A mapping — shallow-copy so isArray / children replacement do not mutate
+  // the caller's parsed-YAML object.
+  return { ...(rawBody as Record<string, unknown>) };
+}