@metaobjectsdev/metadata 0.9.0-rc.1 → 0.10.0

package/src/core/relationship/relationship-definition.embedded.ts

@@ -0,0 +1,317 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/relationship.json
+// Regenerate: bun run scripts/generate-embedded-metamodel.ts
+//
+// Embeds the canonical FR-033 ProviderDefinition so the provider can register
+// itself wherever the on-disk spec/ tree is unavailable (bundled builds).
+import type { ProviderDefinition } from "../../provider-data.js";
+
+export const RELATIONSHIP_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "relationship",
+      "subType": "base",
+      "description": "Abstract relationship base — shared shape for the concrete association/aggregation/composition subtypes; not authored directly.",
+      "rules": "@cardinality is an open string at the metamodel level ('one'/'many', and Java-canonical composite forms such as 'many-to-one'); @objectRef names the target entity. M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. @onDelete/@onUpdate carry referential actions (cascade/set-null/restrict/no-action).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "cardinality",
+          "min": 0,
+          "max": 1,
+          "description": "Cardinality of the relationship target (e.g. 'one', 'many', 'many-to-one')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "objectRef",
+          "min": 0,
+          "max": 1,
+          "description": "Name or fully-qualified name of the target object the relationship points to (e.g. 'Week' or 'acme::vehicle::Car')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "through",
+          "min": 0,
+          "max": 1,
+          "description": "Junction (through) entity name for M:N relationships — a third entity declaring two identity.reference children, one per FK side. The relationship's FK fields are derived from those references."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "sourceRefField",
+          "min": 0,
+          "max": 1,
+          "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "symmetric",
+          "min": 0,
+          "max": 1,
+          "description": "Undirected self-join flag (union-on-read). Valid only when @objectRef == the declaring entity. Mutually exclusive with @sourceRefField."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onDelete",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on parent delete. Default derives from subtype (composition→cascade, aggregation→set-null, association→restrict)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onUpdate",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on key update. Default cascade."
+        }
+      ]
+    },
+    {
+      "type": "relationship",
+      "subType": "association",
+      "description": "A plain reference to another entity — no ownership; the target has an independent lifecycle (default @onDelete restrict).",
+      "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Association is a plain reference — the target's lifecycle is independent (default @onDelete restrict).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "cardinality",
+          "min": 0,
+          "max": 1,
+          "description": "Cardinality of the relationship target (e.g. 'one', 'many', 'many-to-one')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "objectRef",
+          "min": 0,
+          "max": 1,
+          "description": "Name or fully-qualified name of the target object the relationship points to (e.g. 'Week' or 'acme::vehicle::Car')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "through",
+          "min": 0,
+          "max": 1,
+          "description": "Junction (through) entity name for M:N relationships — a third entity declaring two identity.reference children, one per FK side. The relationship's FK fields are derived from those references."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "sourceRefField",
+          "min": 0,
+          "max": 1,
+          "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "symmetric",
+          "min": 0,
+          "max": 1,
+          "description": "Undirected self-join flag (union-on-read). Valid only when @objectRef == the declaring entity. Mutually exclusive with @sourceRefField."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onDelete",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on parent delete. Default derives from subtype (composition→cascade, aggregation→set-null, association→restrict)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onUpdate",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on key update. Default cascade."
+        }
+      ]
+    },
+    {
+      "type": "relationship",
+      "subType": "aggregation",
+      "description": "A shared/independent containment — the parent groups the target but does not own its lifecycle (default @onDelete set-null).",
+      "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Aggregation is shared/independent — the target outlives the parent (default @onDelete set-null).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "cardinality",
+          "min": 0,
+          "max": 1,
+          "description": "Cardinality of the relationship target (e.g. 'one', 'many', 'many-to-one')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "objectRef",
+          "min": 0,
+          "max": 1,
+          "description": "Name or fully-qualified name of the target object the relationship points to (e.g. 'Week' or 'acme::vehicle::Car')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "through",
+          "min": 0,
+          "max": 1,
+          "description": "Junction (through) entity name for M:N relationships — a third entity declaring two identity.reference children, one per FK side. The relationship's FK fields are derived from those references."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "sourceRefField",
+          "min": 0,
+          "max": 1,
+          "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "symmetric",
+          "min": 0,
+          "max": 1,
+          "description": "Undirected self-join flag (union-on-read). Valid only when @objectRef == the declaring entity. Mutually exclusive with @sourceRefField."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onDelete",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on parent delete. Default derives from subtype (composition→cascade, aggregation→set-null, association→restrict)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onUpdate",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on key update. Default cascade."
+        }
+      ]
+    },
+    {
+      "type": "relationship",
+      "subType": "composition",
+      "description": "An owned containment — the parent owns the target's lifecycle; deleting the parent deletes the children (default @onDelete cascade).",
+      "rules": "M:N is expressed by @cardinality:'many' + @objectRef + @through: @through names a junction entity that MUST declare two identity.reference children (one per FK side), and the relationship's FK fields are DERIVED from those references — never restated. @sourceRefField disambiguates a DIRECTED self-join by naming the source-side FK field on the junction; @symmetric marks an UNDIRECTED self-join (union-on-read) valid only when @objectRef == the declaring entity; the two are mutually exclusive. Composition is owned lifecycle — the children do not outlive the parent (default @onDelete cascade).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "cardinality",
+          "min": 0,
+          "max": 1,
+          "description": "Cardinality of the relationship target (e.g. 'one', 'many', 'many-to-one')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "objectRef",
+          "min": 0,
+          "max": 1,
+          "description": "Name or fully-qualified name of the target object the relationship points to (e.g. 'Week' or 'acme::vehicle::Car')."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "through",
+          "min": 0,
+          "max": 1,
+          "description": "Junction (through) entity name for M:N relationships — a third entity declaring two identity.reference children, one per FK side. The relationship's FK fields are derived from those references."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "sourceRefField",
+          "min": 0,
+          "max": 1,
+          "description": "Directed self-join disambiguator: names the source-side FK field on the junction (the other reference is the target side). Required only for directed/ambiguous self-join M:N. Mutually exclusive with @symmetric."
+        },
+        {
+          "type": "attr",
+          "subType": "boolean",
+          "name": "symmetric",
+          "min": 0,
+          "max": 1,
+          "description": "Undirected self-join flag (union-on-read). Valid only when @objectRef == the declaring entity. Mutually exclusive with @sourceRefField."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onDelete",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on parent delete. Default derives from subtype (composition→cascade, aggregation→set-null, association→restrict)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "onUpdate",
+          "min": 0,
+          "max": 1,
+          "allowedValues": [
+            "cascade",
+            "set-null",
+            "restrict",
+            "no-action"
+          ],
+          "description": "Referential action on key update. Default cascade."
+        }
+      ]
+    }
+  ]
+};

package/src/core/validator/validator-definition.embedded.ts

@@ -0,0 +1,141 @@
+// AUTO-GENERATED by scripts/generate-embedded-metamodel.ts — DO NOT EDIT.
+// Canonical source: repo-root spec/metamodel/validator.json
+// Regenerate: bun run scripts/generate-embedded-metamodel.ts
+//
+// Embeds the canonical FR-033 ProviderDefinition so the provider can register
+// itself wherever the on-disk spec/ tree is unavailable (bundled builds).
+import type { ProviderDefinition } from "../../provider-data.js";
+
+export const VALIDATOR_DEFINITION: ProviderDefinition = {
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "validator",
+      "subType": "base",
+      "description": "Abstract base validator — the shared root subtype concrete validators specialize. Carries the @min/@max bounds attrs but enforces no rule of its own.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "min",
+          "min": 0,
+          "max": 1,
+          "description": "Minimum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "max",
+          "min": 0,
+          "max": 1,
+          "description": "Maximum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "required",
+      "description": "Fails when the value is null/empty (NOT NULL). Equivalent to @required on the owning field."
+    },
+    {
+      "type": "validator",
+      "subType": "length",
+      "description": "Bounds string length / collection size via @min/@max.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "min",
+          "min": 0,
+          "max": 1,
+          "description": "Minimum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "max",
+          "min": 0,
+          "max": 1,
+          "description": "Maximum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "regex",
+      "description": "Requires the value match a regular expression (@pattern).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "min",
+          "min": 0,
+          "max": 1,
+          "description": "Minimum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "max",
+          "min": 0,
+          "max": 1,
+          "description": "Maximum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "pattern",
+          "min": 0,
+          "max": 1,
+          "description": "Regular expression the value must match."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "numeric",
+      "description": "Bounds a numeric value's magnitude via @min/@max.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "min",
+          "min": 0,
+          "max": 1,
+          "description": "Minimum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "max",
+          "min": 0,
+          "max": 1,
+          "description": "Maximum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "array",
+      "description": "Bounds the element count of an array-valued field via @min/@max.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "min",
+          "min": 0,
+          "max": 1,
+          "description": "Minimum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        },
+        {
+          "type": "attr",
+          "subType": "int",
+          "name": "max",
+          "min": 0,
+          "max": 1,
+          "description": "Maximum allowed value (length, numeric value, or array element count depending on the validator subtype)."
+        }
+      ]
+    }
+  ]
+};

package/src/core/yaml-desugar.ts

@@ -35,9 +35,13 @@ import {
   RESERVED_KEYS,
   RESERVED_KEY_CHILDREN,
   RESERVED_KEY_NAME,
+  RESERVED_KEY_PACKAGE,
+  RESERVED_KEY_EXTENDS,
   RESERVED_KEY_IS_ARRAY,
   TYPE_SUBTYPE_SEPARATOR,
+  PACKAGE_SEPARATOR,
 } from "../shared/structural.js";
+import { expandRef, REF_BEARING_ATTR_NAMES } from "../naming-refs.js";
 import {
   getPositionMap,
   setPositionMap,
@@ -72,10 +76,34 @@ export interface DesugarResult {
 /** Desugar a parsed-YAML authoring document into a canonical-shaped object. */
 export function desugar(input: unknown, registry: TypeRegistry): DesugarResult {
   const errors: CollectedError[] = [];
-  const node = desugarNode(input, registry, errors, "<root>");
+  // FR-032 (ADR-0032): the desugar threads the effective package context down
+  // the tree so every ref-bearing attr (extends + @objectRef/@references/@from/
+  // @of/@via/@parameterRef/@payloadRef/@responseRef) is expanded to its FQN via
+  // expandRef. The root context is empty (the metadata.root's own `package`
+  // body key seeds the first real context inside desugarNode).
+  const node = desugarNode(input, registry, errors, "<root>", "");
   return { canonical: node ?? {}, errors };
 }
 
+// FR-032: compute a node's effective package from its raw `package` body key
+// (inheriting the parent context when absent). Mirrors parser-core's
+// expandPackageForPath so the desugar's ref-expansion context matches the JSON
+// loader's package resolution. The `package` attr itself is NEVER ref-expanded
+// (ADR-0032 §2.1 — it is the node's identity, taken literally/absolute).
+function effectivePackageFor(rawBody: unknown, parentPkg: string): string {
+  if (typeof rawBody !== "object" || rawBody === null || Array.isArray(rawBody)) {
+    return parentPkg;
+  }
+  const rawPkg = (rawBody as Record<string, unknown>)[RESERVED_KEY_PACKAGE];
+  if (typeof rawPkg !== "string") return parentPkg;
+  // Legacy expandPackageForPath: a leading "::" on a child package prepends the
+  // parent; otherwise it is used as-is.
+  if (parentPkg !== "" && rawPkg.startsWith(PACKAGE_SEPARATOR)) {
+    return parentPkg + rawPkg;
+  }
+  return rawPkg;
+}
+
 // 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).
@@ -84,6 +112,7 @@ function desugarNode(
   registry: TypeRegistry,
   errors: CollectedError[],
   path: string,
+  parentPkg: string,
 ): Record<string, unknown> | undefined {
   if (typeof input !== "object" || input === null || Array.isArray(input)) {
     errors.push({ message: `Node at ${path} must be a mapping with one type key` });
@@ -120,11 +149,16 @@ function desugarNode(
   // Rule 1: a bare `type` key → the type's registry default subType.
   const canonicalKey = resolveKey(key, registry, errors, path);
 
+  // FR-032: this node's effective package context (its own `package` body key,
+  // else inherited). Used to expand its ref-bearing attrs AND threaded to its
+  // children so their bare/relative refs resolve against the right package.
+  const nodePkg = effectivePackageFor(rawBody, parentPkg);
+
   // Rule 2: a scalar body → { name: <scalar> }.
   // FR5b — propagate the wrapper-key's position into the synthesized body
   // when the input body was a scalar (no body-side positions to inherit).
   const wrapperKeyPos = wrapperPositions?.[rawKey];
-  const body = desugarBody(rawBody, registry, canonicalKey, errors, path, wrapperKeyPos);
+  const body = desugarBody(rawBody, registry, canonicalKey, errors, path, wrapperKeyPos, nodePkg);
 
   // Rule 4 (cont.): stamp isArray onto the canonical body.
   if (isArray) body[RESERVED_KEY_IS_ARRAY] = true;
@@ -135,7 +169,7 @@ function desugarNode(
     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);
+      const child = desugarNode(rawChildren[i], registry, errors, childPath, nodePkg);
       // On a bad child keep an empty-object placeholder so sibling indices
       // stay stable; the error is already collected.
       children.push(child ?? {});
@@ -196,6 +230,10 @@ function desugarBody(
    *  empty bodies; for mapping bodies we use the body's own position-by-key
    *  map. */
   wrapperKeyPos: { line: number; col: number } | undefined,
+  /** FR-032: this node's effective package context, used to expand its
+   *  ref-bearing attrs (extends + @objectRef/@references/@from/@of/@via/
+   *  @parameterRef/@payloadRef/@responseRef) to FQN via expandRef. */
+  nodePkg: string,
 ): Record<string, unknown> {
   if (
     typeof rawBody === "string" ||
@@ -241,16 +279,27 @@ function desugarBody(
   for (const key of Object.keys(src)) {
     let outKey: string;
     if (RESERVED_KEYS.has(key) || key.startsWith(ATTR_PREFIX)) {
-      out[key] = src[key];
       outKey = key;
-      // D2 also applies to author-written @-keys (the awkward form).
+      // FR-032: expand a ref-bearing value to FQN. `extends` (reserved) and the
+      // @-prefixed ref attrs are expanded; everything else is copied verbatim.
       const attrName = key.startsWith(ATTR_PREFIX) ? key.slice(ATTR_PREFIX.length) : "";
+      if (key === RESERVED_KEY_EXTENDS || (attrName !== "" && REF_BEARING_ATTR_NAMES.has(attrName))) {
+        out[key] = expandRefValue(src[key], nodePkg, errors, path, key);
+      } else {
+        out[key] = src[key];
+      }
+      // D2 also applies to author-written @-keys (the awkward form).
       if (attrName !== "" && !RESERVED_KEYS.has(attrName)) {
         checkCoercion(attrName, src[key], schemaIndex, errors, path);
       }
     } else {
       outKey = `${ATTR_PREFIX}${key}`;
-      out[outKey] = src[key];
+      // FR-032: a bare (sigil-free) ref-bearing attr is expanded to FQN too.
+      if (REF_BEARING_ATTR_NAMES.has(key)) {
+        out[outKey] = expandRefValue(src[key], nodePkg, errors, path, outKey);
+      } else {
+        out[outKey] = src[key];
+      }
       checkCoercion(key, src[key], schemaIndex, errors, path);
     }
     const pos = srcPositions?.[key];
@@ -263,6 +312,41 @@ function desugarBody(
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// FR-032 (ADR-0032) — expand a ref-bearing value to FQN.
+//
+// A ref value is a single string (most refs) or a string-array (@references can
+// carry multiple). expandRef preserves any FR-024 dotted child suffix and the
+// `package` attr is never touched here (it is not a ref). A parent-relative
+// over-drop (more `..::` than the package has segments) throws inside expandRef;
+// we collect it as ERR_BAD_ATTR_VALUE and pass the raw value through so the rest
+// of the desugar/load proceeds and surfaces a single actionable error.
+// ---------------------------------------------------------------------------
+
+function expandRefValue(
+  raw: unknown,
+  nodePkg: string,
+  errors: CollectedError[],
+  path: string,
+  refLabel: string,
+): unknown {
+  if (typeof raw === "string") {
+    try {
+      return expandRef(raw, nodePkg);
+    } catch (err) {
+      errors.push({
+        message: `Cannot expand reference '${refLabel}' at ${path}: ${(err as Error).message}`,
+        code: "ERR_BAD_ATTR_VALUE",
+      });
+      return raw;
+    }
+  }
+  if (Array.isArray(raw)) {
+    return raw.map((el) => (typeof el === "string" ? expandRefValue(el, nodePkg, errors, path, refLabel) : el));
+  }
+  return raw;
+}
+
 // ---------------------------------------------------------------------------
 // D2 — YAML type-coercion guard
 // ---------------------------------------------------------------------------
@@ -301,7 +385,12 @@ function checkCoercion(
   const spec = schemaIndex.get(attrName);
   if (spec === undefined || spec.valueType === undefined) return;
 
-  switch (spec.valueType) {
+  // Array-valued attr (the `string` + `isArray` model that replaced the
+  // `stringarray` subtype): validate as a string-array regardless of the scalar
+  // valueType token.
+  const effectiveValueType = spec.isArray === true ? ATTR_SUBTYPE_STRINGARRAY : spec.valueType;
+
+  switch (effectiveValueType) {
     case ATTR_SUBTYPE_STRING:
     case ATTR_SUBTYPE_CLASS:
       if (typeof raw !== "string") emitCoercion(attrName, raw, "string", errors, path);