@metaobjectsdev/metadata 0.5.0-rc.1

package/src/loader/validation-passes.ts

@@ -0,0 +1,370 @@
+// Stateless validation passes for the MetaDataLoader pipeline.
+//
+// Each function takes a fully-merged MetaData root and returns errors or
+// warnings. No loader state is read or written — these are pure functions.
+//
+// Exported: validateDataGridSortFields, validateFilterableHasIndex,
+//           validateOriginPaths  (called by MetaDataLoader.load() in order).
+// Private:  _findObject, _findField, _findRelationship,
+//           _validateFromPath, _validateViaPath  (helpers, not exported).
+
+import type { MetaData } from "../shared/meta-data.js";
+import { ParseError } from "../errors.js";
+import {
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_LAYOUT,
+  TYPE_IDENTITY,
+  TYPE_ORIGIN,
+  TYPE_RELATIONSHIP,
+} from "../shared/base-types.js";
+import {
+  LAYOUT_SUBTYPE_DATA_GRID,
+  LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD,
+  LAYOUT_DATA_GRID_ATTR_FILTER,
+} from "../presentation/layout/layout-constants.js";
+import {
+  FIELD_ATTR_FILTERABLE,
+} from "../core/field/field-constants.js";
+import { FIELD_ATTR_DB_INDEXED } from "../persistence/db/db-constants.js";
+import { IDENTITY_ATTR_FIELDS } from "../core/identity/identity-constants.js";
+import {
+  ORIGIN_SUBTYPE_PASSTHROUGH,
+  ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_PASSTHROUGH_ATTR_FROM,
+  ORIGIN_PASSTHROUGH_ATTR_VIA,
+  ORIGIN_AGGREGATE_ATTR_OF,
+  ORIGIN_AGGREGATE_ATTR_VIA,
+} from "../persistence/origin/origin-constants.js";
+import { RELATIONSHIP_ATTR_OBJECT_REF } from "../core/relationship/relationship-constants.js";
+import {
+  FILTER_COMPOSE_OR,
+  FILTER_COMPOSE_AND,
+  opsForSubType,
+} from "../core/query/query-constants.js";
+
+// ---------------------------------------------------------------------------
+// Layout dataGrid @defaultSortField validation
+// ---------------------------------------------------------------------------
+
+export function validateDataGridSortFields(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    // Use children() so inherited fields (via extends:/super:) are
+    // visible when validating @defaultSortField references.
+    const effective = obj.children();
+    const fieldNames = new Set(
+      effective.filter((c) => c.type === TYPE_FIELD).map((f) => f.name),
+    );
+    for (const layout of effective.filter((c) => c.type === TYPE_LAYOUT && c.subType === LAYOUT_SUBTYPE_DATA_GRID)) {
+      const sortField = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
+      if (typeof sortField === "string" && !fieldNames.has(sortField)) {
+        errors.push(
+          new ParseError(
+            `dataGrid layout "${layout.name}" on entity "${obj.name}" has @defaultSortField "${sortField}" ` +
+            `but no such field exists on "${obj.name}". Available fields: ${[...fieldNames].join(", ")}`,
+            { code: "ERR_BAD_DEFAULT_SORT_FIELD" },
+          ),
+        );
+      }
+    }
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// @filterable without index validation
+// ---------------------------------------------------------------------------
+
+export function validateFilterableHasIndex(root: MetaData): string[] {
+  const warnings: string[] = [];
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    // Use children() so inherited fields and identities (via extends:/super:)
+    // are included when checking filterable-without-index.
+    const effective = obj.children();
+    // Build the set of field names that are part of any identity on this object.
+    const indexedFieldNames = new Set<string>();
+    for (const identity of effective.filter((c) => c.type === TYPE_IDENTITY)) {
+      const fields = identity.ownAttr(IDENTITY_ATTR_FIELDS);
+      if (typeof fields === "string") {
+        for (const name of fields.split(",")) indexedFieldNames.add(name.trim());
+      } else if (Array.isArray(fields)) {
+        for (const name of fields) if (typeof name === "string") indexedFieldNames.add(name);
+      }
+    }
+
+    for (const field of effective.filter((c) => c.type === TYPE_FIELD)) {
+      const filterable = field.ownAttr(FIELD_ATTR_FILTERABLE);
+      if (filterable !== true) continue;
+      if (field.ownAttr(FIELD_ATTR_DB_INDEXED) === true) continue;
+      if (indexedFieldNames.has(field.name)) continue;
+      warnings.push(
+        `[filterable-without-index] field "${obj.name}.${field.name}" has @filterable: true but is not ` +
+        `part of any identity. Filtering on this field will sequential-scan. Add @db.indexed: true ` +
+        `to the field (when supported), or remove @filterable: true.`,
+      );
+    }
+  }
+  return warnings;
+}
+
+// ---------------------------------------------------------------------------
+// Origin path validation
+//
+// Walks every projection's fields, finds `origin` (TYPE_ORIGIN) children,
+// and validates:
+//   - passthrough.@from resolves to an existing entity + field
+//   - aggregate.@of resolves to an existing entity + field
+//   - .@via paths resolve through real relationships, hopping entity-by-entity
+//     using each relationship's @objectRef
+//
+// Note: @agg vocabulary is validated by validateAttrSchema (A3 pass) via
+// allowedValues on the origin.aggregate @agg attr schema — not here.
+// ---------------------------------------------------------------------------
+
+function _findObject(root: MetaData, name: string): MetaData | undefined {
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+}
+
+function _findField(obj: MetaData, name: string): MetaData | undefined {
+  // Use children() so inherited fields (via extends:/super:) are included.
+  return obj.children().find((c) => c.type === TYPE_FIELD && c.name === name);
+}
+
+function _findRelationship(obj: MetaData, name: string): MetaData | undefined {
+  // Use children() so inherited relationships (via extends:/super:) are included.
+  return obj.children().find((c) => c.type === TYPE_RELATIONSHIP && c.name === name);
+}
+
+function _validateFromPath(
+  fromAttr: string,
+  root: MetaData,
+  projectionName: string,
+  fieldName: string,
+  errors: ParseError[],
+  label: string = "origin.passthrough.@from",
+): void {
+  const dotIdx = fromAttr.indexOf(".");
+  if (dotIdx < 1 || dotIdx === fromAttr.length - 1) {
+    errors.push(
+      new ParseError(
+        `${label} "${fromAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.field".`,
+        { code: "ERR_INVALID_ORIGIN" },
+      ),
+    );
+    return;
+  }
+  const entityName = fromAttr.slice(0, dotIdx);
+  const targetFieldName = fromAttr.slice(dotIdx + 1);
+  const sourceObj = _findObject(root, entityName);
+  if (!sourceObj) {
+    errors.push(
+      new ParseError(
+        `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
+        { code: "ERR_INVALID_ORIGIN" },
+      ),
+    );
+    return;
+  }
+  const sourceField = _findField(sourceObj, targetFieldName);
+  if (!sourceField) {
+    errors.push(
+      new ParseError(
+        `${label} "${fromAttr}" on ${projectionName}.${fieldName}: no such field "${targetFieldName}" on ${entityName}.`,
+        { code: "ERR_INVALID_ORIGIN" },
+      ),
+    );
+  }
+}
+
+function _validateViaPath(
+  viaAttr: string,
+  root: MetaData,
+  projectionName: string,
+  fieldName: string,
+  errors: ParseError[],
+): void {
+  const segments = viaAttr.split(".");
+  if (segments.length < 2) {
+    errors.push(
+      new ParseError(
+        `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: must be of form "Entity.relationship[.relationship...]".`,
+        { code: "ERR_INVALID_ORIGIN" },
+      ),
+    );
+    return;
+  }
+  const [entityName, ...relSegments] = segments as [string, ...string[]];
+  let currentObj = _findObject(root, entityName);
+  if (!currentObj) {
+    errors.push(
+      new ParseError(
+        `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such entity "${entityName}".`,
+        { code: "ERR_INVALID_ORIGIN" },
+      ),
+    );
+    return;
+  }
+  for (const relName of relSegments) {
+    const rel = _findRelationship(currentObj, relName);
+    if (!rel) {
+      errors.push(
+        new ParseError(
+          `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: no such relationship "${relName}" on ${currentObj.name}.`,
+          { code: "ERR_INVALID_ORIGIN" },
+        ),
+      );
+      return;
+    }
+    const refTarget = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+    if (typeof refTarget !== "string" || refTarget === "") {
+      errors.push(
+        new ParseError(
+          `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" on ${currentObj.name} is missing @objectRef.`,
+          { code: "ERR_INVALID_ORIGIN" },
+        ),
+      );
+      return;
+    }
+    const nextObj = _findObject(root, refTarget);
+    if (!nextObj) {
+      errors.push(
+        new ParseError(
+          `origin.@via "${viaAttr}" on ${projectionName}.${fieldName}: relationship "${relName}" points to non-existent entity "${refTarget}".`,
+          { code: "ERR_INVALID_ORIGIN" },
+        ),
+      );
+      return;
+    }
+    currentObj = nextObj;
+  }
+}
+
+export function validateOriginPaths(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+      for (const origin of field.ownChildren().filter((c) => c.type === TYPE_ORIGIN)) {
+        if (origin.subType === ORIGIN_SUBTYPE_PASSTHROUGH) {
+          const from = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_FROM);
+          if (typeof from !== "string" || from === "") {
+            errors.push(
+              new ParseError(
+                `origin.passthrough on ${obj.name}.${field.name}: missing @from.`,
+                { code: "ERR_INVALID_ORIGIN" },
+              ),
+            );
+            continue;
+          }
+          _validateFromPath(from, root, obj.name, field.name, errors);
+          const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
+          if (typeof via === "string" && via !== "") {
+            _validateViaPath(via, root, obj.name, field.name, errors);
+          }
+        } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
+          const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
+          if (typeof of_ !== "string" || of_ === "") {
+            errors.push(
+              new ParseError(
+                `origin.aggregate on ${obj.name}.${field.name}: missing @of.`,
+                { code: "ERR_INVALID_ORIGIN" },
+              ),
+            );
+            continue;
+          }
+          _validateFromPath(of_, root, obj.name, field.name, errors, "origin.aggregate.@of");
+          const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
+          if (typeof via !== "string" || via === "") {
+            errors.push(
+              new ParseError(
+                `origin.aggregate on ${obj.name}.${field.name}: missing @via (aggregates require a relationship path).`,
+                { code: "ERR_INVALID_ORIGIN" },
+              ),
+            );
+            continue;
+          }
+          _validateViaPath(via, root, obj.name, field.name, errors);
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// Layout dataGrid @filter value validation
+//
+// Runs after extends: resolution (so inherited @filterable fields are visible)
+// and after parse-time desugaring (so every clause is canonical { op: value }).
+// Builds the allowlist from @filterable fields using OPS_BY_SUBTYPE, then checks
+// every filtered field is filterable and every op is allowed for its subtype.
+// ---------------------------------------------------------------------------
+
+export function validateDataGridFilterValues(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    const effective = obj.children();
+    const allow = new Map<string, readonly string[]>();
+    for (const f of effective.filter((c) => c.type === TYPE_FIELD)) {
+      if (f.ownAttr(FIELD_ATTR_FILTERABLE) === true) {
+        allow.set(f.name, opsForSubType(f.subType));
+      }
+    }
+    for (const layout of effective.filter(
+      (c) => c.type === TYPE_LAYOUT && c.subType === LAYOUT_SUBTYPE_DATA_GRID,
+    )) {
+      const filter = layout.ownAttr(LAYOUT_DATA_GRID_ATTR_FILTER);
+      // Type errors (e.g. legacy string form) are reported by validateAttrSchema.
+      if (typeof filter !== "object" || filter === null || Array.isArray(filter)) continue;
+      checkFilterClauses(filter as Record<string, unknown>, allow, obj.name, layout.name, errors);
+    }
+  }
+  return errors;
+}
+
+function checkFilterClauses(
+  filter: Record<string, unknown>,
+  allow: Map<string, readonly string[]>,
+  entityName: string,
+  layoutName: string,
+  errors: ParseError[],
+): void {
+  for (const [key, clause] of Object.entries(filter)) {
+    if (key === FILTER_COMPOSE_OR || key === FILTER_COMPOSE_AND) {
+      if (Array.isArray(clause)) {
+        for (const sub of clause) {
+          if (typeof sub === "object" && sub !== null && !Array.isArray(sub)) {
+            checkFilterClauses(sub as Record<string, unknown>, allow, entityName, layoutName, errors);
+          }
+        }
+      }
+      continue;
+    }
+    const allowedOps = allow.get(key);
+    if (allowedOps === undefined) {
+      errors.push(
+        new ParseError(
+          `dataGrid layout "${layoutName}" on entity "${entityName}" has @filter over ` +
+            `non-filterable field "${key}". Filterable fields: ${[...allow.keys()].join(", ") || "(none)"}`,
+          { code: "ERR_BAD_ATTR_FILTER" },
+        ),
+      );
+      continue;
+    }
+    // After parse-time desugaring (FilterAttr.desugar), every non-composition field clause
+    // is canonical { op: value } — a bare scalar should not reach here; the object guard is defensive.
+    if (typeof clause === "object" && clause !== null && !Array.isArray(clause)) {
+      for (const op of Object.keys(clause)) {
+        if (!allowedOps.includes(op)) {
+          errors.push(
+            new ParseError(
+              `dataGrid layout "${layoutName}" on entity "${entityName}" @filter uses disallowed ` +
+                `op "${key}.${op}". Allowed ops for "${key}": ${allowedOps.join(", ")}`,
+              { code: "ERR_BAD_ATTR_FILTER" },
+            ),
+          );
+        }
+      }
+    }
+  }
+}

package/src/naming.ts

@@ -0,0 +1,86 @@
+import type { MetaData } from "./shared/meta-data.js";
+import { TYPE_FIELD, TYPE_SOURCE } from "./shared/base-types.js";
+import { PACKAGE_SEPARATOR } from "./shared/structural.js";
+import { FIELD_ATTR_DB_COLUMN } from "./persistence/db/db-constants.js";
+import {
+  SOURCE_SUBTYPE_DB_TABLE,
+  SOURCE_SUBTYPE_DB_VIEW,
+  SOURCE_DB_TABLE_ATTR_NAME,
+  SOURCE_ATTR_SCHEMA,
+} from "./persistence/source/source-constants.js";
+
+/**
+ * Strip the package prefix from a metadata-qualified name
+ * (e.g. "pkg::Name" → "Name"). Returns the input unchanged if no
+ * package separator is present. Single canonical helper consumed by
+ * both find-reference (cross-entity lookup) and codegen-ts (FQN
+ * normalization in generated code).
+ */
+export function stripPackage(name: string | undefined): string {
+  if (!name) return "";
+  const idx = name.lastIndexOf(PACKAGE_SEPARATOR);
+  return idx === -1 ? name : name.slice(idx + PACKAGE_SEPARATOR.length);
+}
+
+export function toSnakeCase(s: string): string {
+  return s
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+export function pluralize(s: string): string {
+  if (/(s|x|z|ch|sh)$/i.test(s)) return s + "es";
+  if (/[^aeiou]y$/i.test(s)) return s.slice(0, -1) + "ies";
+  return s + "s";
+}
+
+export function resolveTableName(entity: MetaData): string {
+  const source = entity.ownChildren().find(
+    (c) => c.type === TYPE_SOURCE && c.subType === SOURCE_SUBTYPE_DB_TABLE,
+  );
+  const name = source?.ownAttr(SOURCE_DB_TABLE_ATTR_NAME);
+  if (typeof name === "string" && name !== "") return name;
+  return pluralize(toSnakeCase(entity.name));
+}
+
+export function resolveColumnName(field: MetaData): string {
+  const attr = field.ownAttr(FIELD_ATTR_DB_COLUMN);
+  if (typeof attr === "string") return attr;
+  return toSnakeCase(field.name);
+}
+
+/**
+ * Returns the DB schema declared on an entity's source[dbTable] or source[dbView] child,
+ * or undefined if no @schema attr is set or no source child exists. Callers decide what
+ * "undefined" means for their dialect — Postgres treats it as the default public schema,
+ * SQLite treats it as the only allowed value (no schema concept).
+ */
+export function resolveTableSchema(entity: MetaData): string | undefined {
+  const source = entity.ownChildren().find(
+    (c) => c.type === TYPE_SOURCE
+        && (c.subType === SOURCE_SUBTYPE_DB_TABLE || c.subType === SOURCE_SUBTYPE_DB_VIEW),
+  );
+  if (!source) return undefined;
+  const schema = source.ownAttr(SOURCE_ATTR_SCHEMA);
+  if (typeof schema === "string" && schema !== "") return schema;
+  return undefined;
+}
+
+/** Per-entity {jsName ↔ dbColumn} map. Built once per entity to avoid re-walking children on every row. */
+export interface EntityNameMap {
+  jsToDb: Map<string, string>;
+  dbToJs: Map<string, string>;
+}
+
+export function buildNameMap(entity: MetaData): EntityNameMap {
+  const jsToDb = new Map<string, string>();
+  const dbToJs = new Map<string, string>();
+  for (const child of entity.ownChildren()) {
+    if (child.type !== TYPE_FIELD) continue;
+    const dbCol = resolveColumnName(child);
+    jsToDb.set(child.name, dbCol);
+    dbToJs.set(dbCol, child.name);
+  }
+  return { jsToDb, dbToJs };
+}

package/src/object-serializer.ts

@@ -0,0 +1,153 @@
+// Metadata-driven object serializer.
+//
+// objectToJson / jsonToObject convert application-object instances <-> JSON
+// driven by a MetaObject's field metadata — no per-entity code. Dispatch is on
+// each field's DataType. Plain objects in, plain objects out (the caller does
+// JSON.parse / JSON.stringify). Best-effort and total: neither function throws
+// for malformed instance data, and there is no validation (settled in the
+// spec — Java's object reader does not validate either).
+
+import type { MetaData } from "./shared/meta-data.js";
+import type { MetaObject } from "./core/object/meta-object.js";
+import type { MetaField } from "./core/field/meta-field.js";
+import {
+  DATA_TYPE_BOOLEAN,
+  DATA_TYPE_INT,
+  DATA_TYPE_LONG,
+  DATA_TYPE_DOUBLE,
+  DATA_TYPE_STRING,
+  DATA_TYPE_DATE,
+  DATA_TYPE_OBJECT,
+} from "./data-type.js";
+import { TYPE_OBJECT } from "./shared/base-types.js";
+
+const TYPE_DISCRIMINATOR = "@type";
+
+export interface ObjectSerializeOptions {
+  /** Emit the `@type` discriminator property. Default true. */
+  emitType?: boolean;
+}
+
+/** Serialize an application-object instance to wire JSON, driven by `mo`. */
+export function objectToJson(
+  mo: MetaObject,
+  instance: Record<string, unknown>,
+  opts?: ObjectSerializeOptions,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (opts?.emitType ?? true) {
+    out[TYPE_DISCRIMINATOR] = mo.name;
+  }
+  for (const field of mo.fields()) {
+    const raw = instance[field.name];
+    if (raw === undefined) continue; // absent field → omit
+    out[field.name] = field.isArray
+      ? mapArray(raw, (el) => toJsonValue(field, el, mo))
+      : toJsonValue(field, raw, mo);
+  }
+  return out;
+}
+
+/** Parse wire JSON into an application-object instance, driven by `mo`. */
+export function jsonToObject(
+  mo: MetaObject,
+  json: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const field of mo.fields()) {
+    const raw = json[field.name];
+    if (raw === undefined) continue;
+    out[field.name] = field.isArray
+      ? mapArray(raw, (el) => fromJsonValue(field, el, mo))
+      : fromJsonValue(field, raw, mo);
+  }
+  return out;
+}
+
+// --- write-side conversion -------------------------------------------------
+
+function toJsonValue(field: MetaField, raw: unknown, mo: MetaObject): unknown {
+  switch (field.dataType) {
+    case DATA_TYPE_DATE:
+      return toIsoString(raw);
+    case DATA_TYPE_OBJECT: {
+      const target = resolveObjectRef(field, mo);
+      if (target === undefined || !isPlainObject(raw)) return raw;
+      // Nested objects always carry their own @type (a generic reader needs
+      // it); `emitType: false` suppresses only the top-level discriminator.
+      return objectToJson(target, raw);
+    }
+    case DATA_TYPE_BOOLEAN:
+    case DATA_TYPE_INT:
+    case DATA_TYPE_LONG:
+    case DATA_TYPE_DOUBLE:
+    case DATA_TYPE_STRING:
+    default:
+      return raw; // scalars: already JSON-native, pass through
+  }
+}
+
+// --- read-side conversion --------------------------------------------------
+
+function fromJsonValue(field: MetaField, raw: unknown, mo: MetaObject): unknown {
+  switch (field.dataType) {
+    case DATA_TYPE_BOOLEAN:
+      return coerceBoolean(raw);
+    case DATA_TYPE_INT:
+    case DATA_TYPE_LONG:
+    case DATA_TYPE_DOUBLE:
+      return coerceNumeric(raw);
+    case DATA_TYPE_OBJECT: {
+      const target = resolveObjectRef(field, mo);
+      if (target === undefined || !isPlainObject(raw)) return raw;
+      return jsonToObject(target, raw);
+    }
+    case DATA_TYPE_STRING:
+    case DATA_TYPE_DATE: // kept as the ISO string; the UI builds its own Date
+    default:
+      return raw;
+  }
+}
+
+// --- helpers ---------------------------------------------------------------
+
+function mapArray(raw: unknown, convert: (el: unknown) => unknown): unknown {
+  return Array.isArray(raw) ? raw.map(convert) : raw;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function toIsoString(raw: unknown): unknown {
+  if (raw instanceof Date) return raw.toISOString();
+  if (typeof raw === "number") return new Date(raw).toISOString();
+  return raw; // a string passes through; anything else best-effort
+}
+
+function coerceBoolean(raw: unknown): unknown {
+  if (typeof raw === "boolean") return raw;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  return raw;
+}
+
+function coerceNumeric(raw: unknown): unknown {
+  if (typeof raw === "number") return raw;
+  if (typeof raw === "string" && raw.trim() !== "" && Number.isFinite(Number(raw))) {
+    return Number(raw);
+  }
+  return raw;
+}
+
+/** Resolve an object-typed field's `@objectRef` to its target MetaObject by
+ *  walking to the tree root and looking up the named object child. Returns
+ *  undefined when there is no ref or it does not resolve (caller passes the
+ *  raw value through — best-effort). */
+function resolveObjectRef(field: MetaField, mo: MetaObject): MetaObject | undefined {
+  const ref = field.objectRef;
+  if (ref === undefined) return undefined;
+  const found: MetaData | undefined = mo.root().ownChildByTypeAndName(TYPE_OBJECT, ref);
+  if (found === undefined) return undefined;
+  return found as MetaObject;
+}

package/src/overlay.ts

@@ -0,0 +1,5 @@
+// overlay.ts — empty module.
+//
+// Merging happens during parse via the parser's accumRoot + createOrFindMetaData
+// logic. See parser-json.ts and the per-node isMerge flag on MetaData.
+export {};