@metaobjectsdev/metadata 0.5.0-rc.1

package/src/core-types.ts

@@ -0,0 +1,329 @@
+// registerCoreTypes() — Java's 7 base types (plus metadata wrapper) and their subtypes
+import { TypeId, type AttrSchema, type ChildRule, type TypeDefinition, TypeRegistry } from "./registry.js";
+import type { MetaDataTypeProvider } from "./provider.js";
+import { dbProvider } from "./persistence/db/db-provider.js";
+import { type DataType } from "./data-type.js";
+import type { MetaData } from "./shared/meta-data.js";
+import { MetaRoot } from "./shared/meta-root.js";
+import { MetaObject } from "./core/object/meta-object.js";
+import { MetaField } from "./core/field/meta-field.js";
+import { attrClassFor, type NodeConstructor } from "./attr-class-map.js";
+// Import the attr subclasses for their self-registration side effect (each
+// registers its subtype → class into attr-class-map at module load), so
+// attrClassFor resolves the right class below. The base MetaAttr (the fallback)
+// registers itself; importing a subclass transitively loads meta-attr.ts.
+import "./core/attr/meta-attr-stringarray.js";
+import "./core/attr/meta-attr-filter.js";
+import "./core/attr/meta-attr-properties.js";
+import {
+  MetaValidator,
+  MetaRequiredValidator,
+  MetaLengthValidator,
+  MetaRegexValidator,
+  MetaNumericValidator,
+  MetaArrayValidator,
+} from "./core/validator/meta-validator.js";
+import { MetaView } from "./presentation/view/meta-view.js";
+import {
+  MetaIdentity,
+  MetaPrimaryIdentity,
+  MetaSecondaryIdentity,
+  MetaReferenceIdentity,
+} from "./core/identity/meta-identity.js";
+import { MetaRelationship } from "./core/relationship/meta-relationship.js";
+import { MetaLayout } from "./presentation/layout/meta-layout.js";
+import { MetaSource } from "./persistence/source/meta-source.js";
+import { MetaOrigin, MetaPassthroughOrigin, MetaAggregateOrigin } from "./persistence/origin/meta-origin.js";
+import { commonFieldAttrs, currencyFieldAttr } from "./core/field/field-schema.js";
+import { objectAttrs } from "./core/object/object-schema.js";
+import { relationshipAttrs } from "./core/relationship/relationship-schema.js";
+import { identityFieldsAttr, IDENTITY_ATTRS_MAP } from "./core/identity/identity-schema.js";
+import { VALIDATOR_ATTRS_MAP } from "./core/validator/validator-schema.js";
+import { currencyViewAttrs } from "./presentation/view/view-schema.js";
+import { dataGridLayoutAttrs } from "./presentation/layout/layout-schema.js";
+import { ORIGIN_ATTRS_MAP } from "./persistence/origin/origin-schema.js";
+import {
+  TYPE_METADATA,
+  TYPE_OBJECT,
+  TYPE_FIELD,
+  TYPE_ATTR,
+  TYPE_VALIDATOR,
+  TYPE_VIEW,
+  TYPE_IDENTITY,
+  TYPE_RELATIONSHIP,
+  TYPE_LAYOUT,
+  TYPE_SOURCE,
+  TYPE_ORIGIN,
+  SUBTYPE_ROOT,
+} from "./shared/base-types.js";
+import { CHILD_RULE_WILDCARD } from "./shared/structural.js";
+import { OBJECT_SUBTYPES, OBJECT_SUBTYPE_ENTITY } from "./core/object/object-constants.js";
+import { FIELD_SUBTYPES, FIELD_SUBTYPE_CURRENCY } from "./core/field/field-constants.js";
+import { ATTR_SUBTYPES } from "./core/attr/attr-constants.js";
+import {
+  VALIDATOR_SUBTYPES,
+  VALIDATOR_SUBTYPE_REQUIRED,
+  VALIDATOR_SUBTYPE_LENGTH,
+  VALIDATOR_SUBTYPE_REGEX,
+  VALIDATOR_SUBTYPE_NUMERIC,
+  VALIDATOR_SUBTYPE_ARRAY,
+} from "./core/validator/validator-constants.js";
+import {
+  VIEW_SUBTYPES,
+  VIEW_SUBTYPE_CURRENCY,
+} from "./presentation/view/view-constants.js";
+import {
+  IDENTITY_SUBTYPES,
+  IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_SUBTYPE_SECONDARY,
+  IDENTITY_SUBTYPE_REFERENCE,
+} from "./core/identity/identity-constants.js";
+import { RELATIONSHIP_SUBTYPES } from "./core/relationship/relationship-constants.js";
+import { LAYOUT_SUBTYPES, LAYOUT_SUBTYPE_DATA_GRID } from "./presentation/layout/layout-constants.js";
+import { SOURCE_SUBTYPES } from "./persistence/source/source-constants.js";
+import {
+  ORIGIN_SUBTYPES,
+  ORIGIN_SUBTYPE_PASSTHROUGH,
+  ORIGIN_SUBTYPE_AGGREGATE,
+} from "./persistence/origin/origin-constants.js";
+
+// ---------------------------------------------------------------------------
+// The per-(type, subType) attribute schemas live in per-concern *-schema.ts
+// modules (e.g. core/field/field-schema.ts, persistence/origin/origin-schema.ts).
+// This file keeps only the registration logic: the def() helper, the
+// subtype→class dispatch maps, and registerCoreTypes() itself.
+// ---------------------------------------------------------------------------
+
+function wildcard(childType: string): ChildRule {
+  return {
+    childType,
+    childSubType: CHILD_RULE_WILDCARD,
+    childName: CHILD_RULE_WILDCARD,
+  };
+}
+
+function def(
+  type: string,
+  subType: string,
+  description: string,
+  childRules: ChildRule[],
+  NodeClass: NodeConstructor,
+  attributes: AttrSchema[] = [],
+  dataType?: DataType,
+): TypeDefinition {
+  const definition: TypeDefinition = {
+    typeId: new TypeId(type, subType),
+    description,
+    factory: (typeId, name) => {
+      const node = new NodeClass(typeId, name);
+      if (dataType !== undefined) node.setDataType(dataType);
+      return node;
+    },
+    childRules,
+    attributes,
+  };
+  if (dataType !== undefined) definition.dataType = dataType;
+  return definition;
+}
+
+/** Map from validator subtype string → concrete node constructor. */
+const VALIDATOR_CLASS_MAP = new Map<string, NodeConstructor>([
+  [VALIDATOR_SUBTYPE_REQUIRED, MetaRequiredValidator],
+  [VALIDATOR_SUBTYPE_LENGTH, MetaLengthValidator],
+  [VALIDATOR_SUBTYPE_REGEX, MetaRegexValidator],
+  [VALIDATOR_SUBTYPE_NUMERIC, MetaNumericValidator],
+  [VALIDATOR_SUBTYPE_ARRAY, MetaArrayValidator],
+]);
+
+/** Map from identity subtype string → concrete node constructor. */
+const IDENTITY_CLASS_MAP = new Map<string, NodeConstructor>([
+  [IDENTITY_SUBTYPE_PRIMARY, MetaPrimaryIdentity],
+  [IDENTITY_SUBTYPE_SECONDARY, MetaSecondaryIdentity],
+  [IDENTITY_SUBTYPE_REFERENCE, MetaReferenceIdentity],
+]);
+
+/** Map from origin subtype string → concrete node constructor. */
+const ORIGIN_CLASS_MAP = new Map<string, NodeConstructor>([
+  [ORIGIN_SUBTYPE_PASSTHROUGH, MetaPassthroughOrigin],
+  [ORIGIN_SUBTYPE_AGGREGATE, MetaAggregateOrigin],
+]);
+
+// ATTR_CLASS_MAP + attrClassFor live in the leaf module ./attr-class-map.ts
+// (imported above) so MetaData.setAttr can resolve an attr subclass without
+// importing this module — that import created a module-eval cycle. They are
+// re-exported from the package index for the same public surface.
+
+function registerCoreTypeDefs(registry: TypeRegistry): void {
+  // metadata — 1 subtype (the document root: metadata.root)
+  registry.register(
+    def(TYPE_METADATA, SUBTYPE_ROOT, "Root metadata document", [
+      wildcard(TYPE_OBJECT),
+      wildcard(TYPE_FIELD),
+      wildcard(TYPE_ATTR),
+      wildcard(TYPE_VALIDATOR),
+    ], MetaRoot),
+  );
+
+  // object — 4 subtypes
+  const objectRules = [
+    wildcard(TYPE_FIELD),
+    wildcard(TYPE_IDENTITY),
+    wildcard(TYPE_RELATIONSHIP),
+    wildcard(TYPE_VALIDATOR),
+    wildcard(TYPE_LAYOUT),
+    wildcard(TYPE_SOURCE),
+    wildcard(TYPE_ATTR),
+  ];
+  for (const subType of OBJECT_SUBTYPES) {
+    registry.register(
+      def(TYPE_OBJECT, subType, `Object/entity (${subType})`, objectRules, MetaObject, [...objectAttrs]),
+    );
+  }
+
+  // field — 13 subtypes
+  const fieldRules = [
+    wildcard(TYPE_VALIDATOR),
+    wildcard(TYPE_VIEW),
+    wildcard(TYPE_ATTR),
+    wildcard(TYPE_ORIGIN),
+  ];
+  for (const subType of FIELD_SUBTYPES) {
+    // field.currency additionally carries @currency; all other field subtypes
+    // share the common codegen/filter attrs only.
+    const fieldAttrs =
+      subType === FIELD_SUBTYPE_CURRENCY
+        ? [...commonFieldAttrs, { ...currencyFieldAttr }]
+        : [...commonFieldAttrs];
+    registry.register(
+      def(TYPE_FIELD, subType, `Field of type ${subType}`, fieldRules, MetaField, fieldAttrs,
+        new MetaField(new TypeId(TYPE_FIELD, subType), "").dataType),
+    );
+  }
+
+  // attr — 9 subtypes, no children allowed. Each subtype's class owns its
+  // dataType (resolved by this.subType); we read it off a probe instance so the
+  // TypeDefinition.dataType contract (registry.find(...).dataType) still holds.
+  for (const subType of ATTR_SUBTYPES) {
+    const AttrClass = attrClassFor(subType);
+    const probeDataType = new AttrClass(new TypeId(TYPE_ATTR, subType), "").dataType;
+    registry.register(
+      def(TYPE_ATTR, subType, `Attribute of type ${subType}`, [], AttrClass, [], probeDataType),
+    );
+  }
+
+  // validator — 6 subtypes (base + 5 named); dispatch to subtype-specific class.
+  // Subtype→class dispatch for TYPE_VALIDATOR (formerly handled by metaOf()):
+  //   required → MetaRequiredValidator, length → MetaLengthValidator,
+  //   regex → MetaRegexValidator, numeric → MetaNumericValidator,
+  //   array → MetaArrayValidator, default (base) → MetaValidator.
+  // Attr schemas: MetaValidator (base) + length/numeric/array read @min/@max via
+  //   this.ownAttr(VALIDATOR_ATTR_MIN/MAX); regex also reads @pattern via this.ownAttr().
+  //   required has no extra attrs.
+  const validatorRules = [wildcard(TYPE_ATTR)];
+  for (const subType of VALIDATOR_SUBTYPES) {
+    const NodeClass = VALIDATOR_CLASS_MAP.get(subType) ?? MetaValidator;
+    const validatorAttrs = VALIDATOR_ATTRS_MAP.get(subType) ?? [];
+    registry.register(
+      def(TYPE_VALIDATOR, subType, `Validator (${subType})`, validatorRules, NodeClass, validatorAttrs),
+    );
+  }
+
+  // view — N subtypes. Each view permits only attr children (Java parity:
+  // MetaView only attaches to fields, never aggregates child views).
+  // Only view.currency carries a documented attr (@locale); others have none.
+  for (const subType of VIEW_SUBTYPES) {
+    const viewAttrs = subType === VIEW_SUBTYPE_CURRENCY ? [...currencyViewAttrs] : [];
+    registry.register(
+      def(TYPE_VIEW, subType, `View (${subType})`, [wildcard(TYPE_ATTR)], MetaView, viewAttrs),
+    );
+  }
+
+  // layout — object-level UI surfaces (data grids, forms, tabs, cards).
+  // Each subtype permits only attr children — like views, layouts are config carriers.
+  for (const subType of LAYOUT_SUBTYPES) {
+    const layoutAttrs = subType === LAYOUT_SUBTYPE_DATA_GRID ? [...dataGridLayoutAttrs] : [];
+    registry.register(
+      def(TYPE_LAYOUT, subType, `Layout (${subType})`, [wildcard(TYPE_ATTR)], MetaLayout, layoutAttrs),
+    );
+  }
+
+  // source — declares where an object's data lives (dbTable, dbView, ...).
+  // Only attr children; sources carry only configuration, never nested structure.
+  // DB-domain attrs (@name) are added by dbProvider via TypeRegistry.extend.
+  for (const subType of SOURCE_SUBTYPES) {
+    registry.register(
+      def(TYPE_SOURCE, subType, `Source (${subType})`, [wildcard(TYPE_ATTR)], MetaSource, []),
+    );
+  }
+
+  // origin — field-level provenance. Only attr children.
+  // Subtype→class dispatch (mirrors validator / identity patterns):
+  //   passthrough → MetaPassthroughOrigin, aggregate → MetaAggregateOrigin,
+  //   base (and any unmapped subtype) → MetaOrigin.
+  for (const subType of ORIGIN_SUBTYPES) {
+    const NodeClass = ORIGIN_CLASS_MAP.get(subType) ?? MetaOrigin;
+    const originAttrs = ORIGIN_ATTRS_MAP.get(subType) ?? [];
+    registry.register(
+      def(TYPE_ORIGIN, subType, `Origin (${subType})`, [wildcard(TYPE_ATTR)], NodeClass, originAttrs),
+    );
+  }
+
+  // identity — 2 subtypes (no base; Java doesn't register one).
+  // Subtype→class dispatch for TYPE_IDENTITY (formerly handled by metaOf()):
+  //   primary → MetaPrimaryIdentity, secondary → MetaSecondaryIdentity,
+  //   default → MetaIdentity (fallback, not currently registered).
+  for (const subType of IDENTITY_SUBTYPES) {
+    const NodeClass = IDENTITY_CLASS_MAP.get(subType) ?? MetaIdentity;
+    const idAttrs = IDENTITY_ATTRS_MAP.get(subType) ?? [{ ...identityFieldsAttr }];
+    registry.register(
+      def(TYPE_IDENTITY, subType, `Identity (${subType})`, [wildcard(TYPE_ATTR)], NodeClass, idAttrs),
+    );
+  }
+
+  // relationship — 4 subtypes
+  for (const subType of RELATIONSHIP_SUBTYPES) {
+    registry.register(
+      def(
+        TYPE_RELATIONSHIP,
+        subType,
+        `Relationship (${subType})`,
+        [wildcard(TYPE_ATTR)],
+        MetaRelationship,
+        [...relationshipAttrs],
+      ),
+    );
+  }
+
+  // Default subTypes for YAML authoring sugar: a bare `metadata:` / `object:`
+  // key resolves to these. `metadata` has exactly one subtype (root) so the
+  // default is unambiguous; `object` defaults to `entity`, the common case.
+  // Other types (field, validator, ...) have no default — authoring always
+  // writes the full `type.subType`.
+  registry.setDefaultSubType(TYPE_METADATA, SUBTYPE_ROOT);
+  registry.setDefaultSubType(TYPE_OBJECT, OBJECT_SUBTYPE_ENTITY);
+}
+
+/**
+ * The core metaobjects metamodel — the seven base types (object, field, attr,
+ * validator, view, identity, relationship) plus layout / source / origin and
+ * the metadata root. One provider per package: this is `@metaobjectsdev/metadata`'s.
+ */
+export const coreTypesProvider: MetaDataTypeProvider = {
+  id: "metaobjects-core-types",
+  description: "Core metaobjects metamodel types and subtypes.",
+  registerTypes(registry: TypeRegistry): void {
+    registerCoreTypeDefs(registry);
+  },
+};
+
+/** The default provider bundle — core metamodel types plus DB-domain attrs.
+ *  Spread it to add more: `[...coreProviders, mine]`. */
+export const coreProviders: readonly MetaDataTypeProvider[] = [coreTypesProvider, dbProvider];
+
+/**
+ * Register the core metamodel into an existing registry. Thin convenience
+ * wrapper over `coreTypesProvider`; prefer `composeRegistry(coreProviders)`.
+ */
+export function registerCoreTypes(registry: TypeRegistry): void {
+  coreTypesProvider.registerTypes(registry);
+}

package/src/data-converter.ts

@@ -0,0 +1,125 @@
+// Data converter — convert a raw parsed value to a *known* DataType.
+//
+// The TypeScript counterpart of Java's DataConverter.toTypeSafe: directional
+// (toward a type already known from the registered schema), never inferential.
+// Replaces the deleted value-coerce.ts. See
+// docs/superpowers/specs/2026-05-17-data-converter-design.md.
+
+import type { AttrValue } from "./shared/meta-data.js";
+import {
+  type DataType,
+  DATA_TYPE_BOOLEAN,
+  DATA_TYPE_INT,
+  DATA_TYPE_LONG,
+  DATA_TYPE_DOUBLE,
+  DATA_TYPE_OBJECT,
+} from "./data-type.js";
+
+/**
+ * Convert a raw parsed value to a valid AttrValue for a *known* DataType.
+ * Throws for input that cannot be a valid attr value (null / undefined /
+ * nested array). A plain object reaching a scalar branch is stringified by
+ * `String()` — callers that must reject objects use `toAttrValue`.
+ */
+export function convertToDataType(dataType: DataType, raw: unknown): AttrValue {
+  rejectNullish(raw, "convertToDataType");
+
+  // An array value → string[] regardless of the scalar DataType — the only
+  // array shape AttrValue admits (e.g. a stringArray attr).
+  if (Array.isArray(raw)) return toStringArray(raw);
+
+  switch (dataType) {
+    case DATA_TYPE_BOOLEAN:
+      return toBoolean(raw);
+    case DATA_TYPE_INT:
+    case DATA_TYPE_LONG:
+      return toInteger(raw);
+    case DATA_TYPE_DOUBLE:
+      return toDouble(raw);
+    case DATA_TYPE_OBJECT:
+      // Object-typed attrs (filter / properties) store the object verbatim.
+      // A non-object (e.g. a legacy JSON string) is returned as-is so the
+      // attr-schema pass can reject it with ERR_BAD_ATTR_VALUE.
+      return (typeof raw === "object" && raw !== null)
+        ? (raw as AttrValue)
+        : String(raw);
+    // string, date (unreachable for attrs) — string form
+    default:
+      return String(raw);
+  }
+}
+
+/**
+ * Make a raw value a valid AttrValue with NO known type — for an undeclared
+ * `@`-attr. No type-directed conversion and no inference: scalars are stored
+ * as-is (a numeric-looking string stays a string), arrays become string[],
+ * objects/null/undefined are rejected.
+ */
+export function toAttrValue(raw: unknown): AttrValue {
+  rejectNullish(raw, "toAttrValue");
+  if (Array.isArray(raw)) return toStringArray(raw);
+  if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") {
+    return raw;
+  }
+  throw new Error(`toAttrValue: ${typeof raw} is not a valid attr value`);
+}
+
+// --- helpers ---------------------------------------------------------------
+
+function rejectNullish(raw: unknown, fn: string): void {
+  if (raw === null) throw new Error(`${fn}: null is not a valid attr value`);
+  if (raw === undefined) throw new Error(`${fn}: undefined is not a valid attr value`);
+}
+
+function toBoolean(raw: unknown): AttrValue {
+  if (typeof raw === "boolean") return raw;
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  // Not boolean-shaped — best-effort: leave it for attr-schema validation.
+  return raw as AttrValue;
+}
+
+function toInteger(raw: unknown): AttrValue {
+  if (typeof raw === "number") {
+    if (Number.isInteger(raw) && !Number.isSafeInteger(raw)) return String(raw);
+    return raw;
+  }
+  if (typeof raw === "string") {
+    // Strict integer string (e.g. "42", "-7").
+    if (/^-?\d+$/.test(raw)) {
+      const parsed = Number(raw);
+      // Beyond MAX_SAFE_INTEGER → keep verbatim to preserve precision.
+      return Number.isSafeInteger(parsed) ? parsed : raw;
+    }
+    // Float-format strings that represent a whole number (e.g. "3.0", "12.0").
+    // Metadata files sometimes store int attr values in float notation; convert
+    // to the integer value to preserve byte-identical behavior with the old
+    // coerceAttrValue, which parsed these via the double pattern.
+    const parsed = Number(raw);
+    if (Number.isFinite(parsed) && Number.isInteger(parsed) && Number.isSafeInteger(parsed)) {
+      return parsed;
+    }
+  }
+  return raw as AttrValue;
+}
+
+function toDouble(raw: unknown): AttrValue {
+  if (typeof raw === "number") return raw;
+  if (typeof raw === "string") {
+    const parsed = Number(raw);
+    if (raw.trim() !== "" && Number.isFinite(parsed)) return parsed;
+  }
+  return raw as AttrValue;
+}
+
+function toStringArray(arr: unknown[]): string[] {
+  return arr.map((el, i) => {
+    if (Array.isArray(el)) {
+      throw new Error(`array element at index ${i} is a nested array — not supported`);
+    }
+    if (el === null || el === undefined) {
+      throw new Error(`array element at index ${i} is null/undefined`);
+    }
+    return String(el);
+  });
+}

package/src/data-type.ts

@@ -0,0 +1,33 @@
+// DataType — a coarse, cross-cutting value-type classification.
+//
+// Java-`DataTypes` parity: a small closed set that both fields and attributes
+// classify into (a `MetaField`/`MetaAttr` subtype maps to exactly one DataType).
+// Registry-driven — a (type, subType)'s DataType is declared on its
+// TypeDefinition, never in a central switch here. This module stays small and
+// stable: just the union, its constants, and the DataTypeAware interface.
+
+export const DATA_TYPE_BOOLEAN = "boolean";
+export const DATA_TYPE_INT = "int";
+export const DATA_TYPE_LONG = "long";
+export const DATA_TYPE_DOUBLE = "double";
+export const DATA_TYPE_STRING = "string";
+export const DATA_TYPE_DATE = "date";
+export const DATA_TYPE_OBJECT = "object";
+
+/** The closed set of coarse value types. */
+export const DATA_TYPES = [
+  DATA_TYPE_BOOLEAN,
+  DATA_TYPE_INT,
+  DATA_TYPE_LONG,
+  DATA_TYPE_DOUBLE,
+  DATA_TYPE_STRING,
+  DATA_TYPE_DATE,
+  DATA_TYPE_OBJECT,
+] as const;
+
+export type DataType = (typeof DATA_TYPES)[number];
+
+/** Implemented by nodes that carry a typed value — MetaField and MetaAttr. */
+export interface DataTypeAware {
+  readonly dataType: DataType;
+}

package/src/errors.ts

@@ -0,0 +1,68 @@
+// Typed error classes for the metadata parser.
+
+/** Stable, language-neutral error codes — mirrors fixtures/conformance/ERROR-CODES.json. */
+// NOTE: The following codes are forward-declared (no emitting site in the current
+// TS parser/loader — the condition is not yet detected):
+//   - ERR_DUPLICATE_NAME: parser silently reuses existing same-name nodes (find-or-create).
+//   - ERR_MISSING_SUBTYPE: missing subType is resolved to the registry default, never an error.
+//   - ERR_INVALID_SUBTYPE_CHILD: no child-rule validation pass exists yet.
+// Cross-language conformance consumers should not expect these codes from the TS adapter.
+export const ERROR_CODES = [
+  "ERR_TOP_LEVEL_NOT_OBJECT",
+  "ERR_UNKNOWN_TYPE",
+  "ERR_UNKNOWN_SUBTYPE",
+  "ERR_MISSING_SUBTYPE",
+  "ERR_DUPLICATE_NAME",
+  "ERR_UNRESOLVED_SUPER",
+  "ERR_INVALID_SUBTYPE_CHILD",
+  "ERR_UNKNOWN_ATTR",
+  "ERR_BAD_ATTR_VALUE",
+  "ERR_BAD_DEFAULT_SORT_FIELD",
+  "ERR_PROVIDER_DEPENDENCY_CYCLE",
+  "ERR_PROVIDER_DUPLICATE_ID",
+  "ERR_PROVIDER_MISSING_DEPENDENCY",
+  "ERR_PROVIDER_ATTR_CONFLICT",
+  "ERR_MALFORMED_JSON",
+  "ERR_MISSING_REQUIRED_ATTR",
+  "ERR_SUBTYPE_RULE_VIOLATION",
+  "ERR_OVERLAY_NO_TARGET",
+  "ERR_MALFORMED_YAML",
+  "ERR_INVALID_ORIGIN",
+  "ERR_BAD_ATTR_FILTER",
+  "ERR_UNKNOWN",
+] as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[number];
+
+export class ParseError extends Error {
+  readonly source: string | undefined;
+  readonly path: string | undefined; // logical path within the JSON, e.g. "metadata.children[2].field"
+  readonly code: ErrorCode | undefined;
+
+  constructor(
+    message: string,
+    opts?: { source?: string; path?: string; code?: ErrorCode },
+  ) {
+    super(message);
+    this.name = "ParseError";
+    this.source = opts?.source;
+    this.path = opts?.path;
+    this.code = opts?.code;
+  }
+}
+
+/**
+ * Error class for metamodel-level errors that are not parse errors — e.g.
+ * provider composition failures (dependency cycles, missing dependencies,
+ * attribute conflicts). Carries the same stable `.code` field as ParseError
+ * for cross-language conformance.
+ */
+export class MetaModelError extends Error {
+  readonly code: ErrorCode | undefined;
+
+  constructor(message: string, opts?: { code?: ErrorCode }) {
+    super(message);
+    this.name = "MetaModelError";
+    this.code = opts?.code;
+  }
+}