@metaobjectsdev/metadata 0.5.0-rc.1

package/dist/shared/structural.d.ts

@@ -0,0 +1,20 @@
+export declare const RESERVED_KEY_NAME = "name";
+export declare const RESERVED_KEY_PACKAGE = "package";
+export declare const RESERVED_KEY_EXTENDS = "extends";
+export declare const RESERVED_KEY_ABSTRACT = "abstract";
+export declare const RESERVED_KEY_OVERLAY = "overlay";
+export declare const RESERVED_KEY_IS_ARRAY = "isArray";
+export declare const RESERVED_KEY_CHILDREN = "children";
+/** attr-child-node body key carrying the typed value. */
+export declare const RESERVED_KEY_VALUE = "value";
+export declare const RESERVED_KEYS: Set<string>;
+export declare const JSON_KEY_SCHEMA = "$schema";
+export declare const ATTR_PREFIX = "@";
+/** Separator fusing type and subType in a node's wrapper key (`object.entity`). */
+export declare const TYPE_SUBTYPE_SEPARATOR = ".";
+/** Separator between package segments and between package and name. */
+export declare const PACKAGE_SEPARATOR = "::";
+/** Relative-reference "go up one level" marker. */
+export declare const PACKAGE_PARENT = "..";
+export declare const CHILD_RULE_WILDCARD = "*";
+//# sourceMappingURL=structural.d.ts.map

package/dist/shared/structural.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural.d.ts","sourceRoot":"","sources":["../../src/shared/structural.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,iBAAiB,SAAS,CAAC;AACxC,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAC9C,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAC9C,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAChD,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAC9C,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAC/C,eAAO,MAAM,qBAAqB,aAAa,CAAC;AAEhD,yDAAyD;AACzD,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C,eAAO,MAAM,aAAa,aASxB,CAAC;AAMH,eAAO,MAAM,eAAe,YAAY,CAAC;AAMzC,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,mFAAmF;AACnF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAM1C,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,mDAAmD;AACnD,eAAO,MAAM,cAAc,OAAO,CAAC;AAMnC,eAAO,MAAM,mBAAmB,MAAM,CAAC"}

package/dist/shared/structural.js

@@ -0,0 +1,49 @@
+// Structural vocabulary — reserved body keys, JSON special keys, separators, wildcards, package paths.
+// ---------------------------------------------------------------------------
+// Reserved structural body keys (redesigned format — NOT @-prefixed, NOT attrs)
+//
+// Every node body is a map whose only permitted non-@ keys are these. The
+// canonical body-key order is: name, package, extends, abstract, overlay,
+// isArray, @-attrs (alphabetical), children.
+// ---------------------------------------------------------------------------
+export const RESERVED_KEY_NAME = "name";
+export const RESERVED_KEY_PACKAGE = "package";
+export const RESERVED_KEY_EXTENDS = "extends"; // the supertype reference
+export const RESERVED_KEY_ABSTRACT = "abstract"; // true → the node is abstract
+export const RESERVED_KEY_OVERLAY = "overlay"; // true → re-opens an existing same-named node
+export const RESERVED_KEY_IS_ARRAY = "isArray"; // true → the node is an array
+export const RESERVED_KEY_CHILDREN = "children";
+/** attr-child-node body key carrying the typed value. */
+export const RESERVED_KEY_VALUE = "value";
+export const RESERVED_KEYS = new Set([
+    RESERVED_KEY_NAME,
+    RESERVED_KEY_PACKAGE,
+    RESERVED_KEY_EXTENDS,
+    RESERVED_KEY_ABSTRACT,
+    RESERVED_KEY_OVERLAY,
+    RESERVED_KEY_IS_ARRAY,
+    RESERVED_KEY_CHILDREN,
+    RESERVED_KEY_VALUE,
+]);
+// ---------------------------------------------------------------------------
+// JSON document special keys (top-level, ignored during wrapper-key detection)
+// ---------------------------------------------------------------------------
+export const JSON_KEY_SCHEMA = "$schema";
+// ---------------------------------------------------------------------------
+// Inline attribute prefix + fused type.subType key separator
+// ---------------------------------------------------------------------------
+export const ATTR_PREFIX = "@";
+/** Separator fusing type and subType in a node's wrapper key (`object.entity`). */
+export const TYPE_SUBTYPE_SEPARATOR = ".";
+// ---------------------------------------------------------------------------
+// Package path conventions
+// ---------------------------------------------------------------------------
+/** Separator between package segments and between package and name. */
+export const PACKAGE_SEPARATOR = "::";
+/** Relative-reference "go up one level" marker. */
+export const PACKAGE_PARENT = "..";
+// ---------------------------------------------------------------------------
+// Wildcard for child-rule matching
+// ---------------------------------------------------------------------------
+export const CHILD_RULE_WILDCARD = "*";
+//# sourceMappingURL=structural.js.map

package/dist/shared/structural.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"structural.js","sourceRoot":"","sources":["../../src/shared/structural.ts"],"names":[],"mappings":"AAAA,uGAAuG;AAEvG,8EAA8E;AAC9E,gFAAgF;AAChF,EAAE;AACF,0EAA0E;AAC1E,0EAA0E;AAC1E,6CAA6C;AAC7C,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AACxC,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC;AAC9C,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC,CAAG,0BAA0B;AAC3E,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC,CAAC,8BAA8B;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,CAAC,CAAG,8CAA8C;AAC/F,MAAM,CAAC,MAAM,qBAAqB,GAAG,SAAS,CAAC,CAAE,8BAA8B;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,UAAU,CAAC;AAEhD,yDAAyD;AACzD,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC;AAE1C,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,GAAG,CAAS;IAC3C,iBAAiB;IACjB,oBAAoB;IACpB,oBAAoB;IACpB,qBAAqB;IACrB,oBAAoB;IACpB,qBAAqB;IACrB,qBAAqB;IACrB,kBAAkB;CACnB,CAAC,CAAC;AAEH,8EAA8E;AAC9E,+EAA+E;AAC/E,8EAA8E;AAE9E,MAAM,CAAC,MAAM,eAAe,GAAG,SAAS,CAAC;AAEzC,8EAA8E;AAC9E,6DAA6D;AAC7D,8EAA8E;AAE9E,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAE/B,mFAAmF;AACnF,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C,8EAA8E;AAC9E,2BAA2B;AAC3B,8EAA8E;AAE9E,uEAAuE;AACvE,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAEtC,mDAAmD;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAC;AAEnC,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAE9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,GAAG,CAAC"}

package/dist/subtype-rules.d.ts

@@ -0,0 +1,8 @@
+import type { MetaData } from "./shared/meta-data.js";
+import { ParseError } from "./errors.js";
+export interface SubtypeRuleResult {
+    errors: ParseError[];
+    warnings: string[];
+}
+export declare function validateSubtypeRules(root: MetaData): SubtypeRuleResult;
+//# sourceMappingURL=subtype-rules.d.ts.map

package/dist/subtype-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtype-rules.d.ts","sourceRoot":"","sources":["../src/subtype-rules.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAQzC,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,QAAQ,GAAG,iBAAiB,CAKtE"}

package/dist/subtype-rules.js

@@ -0,0 +1,34 @@
+// Cross-language subtype rules for object subtypes.
+//
+//   - value objects MUST NOT have a primary identity (error)
+//   - entity objects SHOULD have a primary identity, unless @isAbstract (warning)
+//   - base objects have no rule (template, may or may not have identity)
+import { ParseError } from "./errors.js";
+import { TYPE_OBJECT, TYPE_IDENTITY } from "./shared/base-types.js";
+import { IDENTITY_SUBTYPE_PRIMARY } from "./core/identity/identity-constants.js";
+import { OBJECT_SUBTYPE_ENTITY, OBJECT_SUBTYPE_VALUE, } from "./core/object/object-constants.js";
+export function validateSubtypeRules(root) {
+    const errors = [];
+    const warnings = [];
+    walk(root, errors, warnings);
+    return { errors, warnings };
+}
+function walk(model, errors, warnings) {
+    if (model.type === TYPE_OBJECT) {
+        const hasPrimary = model.children().some((c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_PRIMARY);
+        if (model.subType === OBJECT_SUBTYPE_VALUE && hasPrimary) {
+            errors.push(new ParseError(`value object '${model.fqn()}' must not have a primary identity ` +
+                `(use subType: "entity" for records with identity)`, { code: "ERR_SUBTYPE_RULE_VIOLATION" }));
+        }
+        else if (model.subType === OBJECT_SUBTYPE_ENTITY &&
+            !hasPrimary &&
+            !model.isAbstract) {
+            warnings.push(`entity object '${model.fqn()}' has no primary identity ` +
+                `(add an identity child or mark @isAbstract: true)`);
+        }
+    }
+    for (const child of model.ownChildren()) {
+        walk(child, errors, warnings);
+    }
+}
+//# sourceMappingURL=subtype-rules.js.map

package/dist/subtype-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtype-rules.js","sourceRoot":"","sources":["../src/subtype-rules.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,EAAE;AACF,6DAA6D;AAC7D,kFAAkF;AAClF,yEAAyE;AAGzE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uCAAuC,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mCAAmC,CAAC;AAO3C,MAAM,UAAU,oBAAoB,CAAC,IAAc;IACjD,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC7B,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC9B,CAAC;AAED,SAAS,IAAI,CAAC,KAAe,EAAE,MAAoB,EAAE,QAAkB;IACrE,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC/B,MAAM,UAAU,GAAG,KAAK,CAAC,QAAQ,EAAE,CAAC,IAAI,CACtC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,OAAO,KAAK,wBAAwB,CAC1E,CAAC;QACF,IAAI,KAAK,CAAC,OAAO,KAAK,oBAAoB,IAAI,UAAU,EAAE,CAAC;YACzD,MAAM,CAAC,IAAI,CACT,IAAI,UAAU,CACZ,iBAAiB,KAAK,CAAC,GAAG,EAAE,qCAAqC;gBAC/D,mDAAmD,EACrD,EAAE,IAAI,EAAE,4BAA4B,EAAE,CACvC,CACF,CAAC;QACJ,CAAC;aAAM,IACL,KAAK,CAAC,OAAO,KAAK,qBAAqB;YACvC,CAAC,UAAU;YACX,CAAC,KAAK,CAAC,UAAU,EACjB,CAAC;YACD,QAAQ,CAAC,IAAI,CACX,kBAAkB,KAAK,CAAC,GAAG,EAAE,4BAA4B;gBACvD,mDAAmD,CACtD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAChC,CAAC;AACH,CAAC"}

package/dist/super-resolve.d.ts

@@ -0,0 +1,34 @@
+import type { MetaData } from "./shared/meta-data.js";
+/**
+ * Resolve a single super reference string against a tree.
+ *
+ * Called by the parser IMMEDIATELY when a node with a `super` key is created,
+ * against the loader's accumulating root (intoRoot). Java semantics: if the
+ * ref cannot be resolved, the parser throws ParseError.
+ *
+ * @param ref - The raw super reference (e.g., "Fruit", "::pkg::Name", "..::common::id")
+ * @param contextPackage - The package of the model whose super is being resolved
+ * @param root - The root MetaData of the accumulating tree to search within
+ * @returns The resolved MetaData, or undefined if the reference cannot be resolved
+ */
+export declare function resolveSuperRef(ref: string, contextPackage: string, root: MetaData): MetaData | undefined;
+export interface DeferredSuperFailure {
+    /** FQN of the node whose super ref could not be resolved. */
+    nodeFqn: string;
+    /** The raw super ref string that didn't resolve. */
+    ref: string;
+}
+/**
+ * Walk the tree and resolve every node's superRef against the full root.
+ * Used by Loader.loadJsonStrings as a second pass after all input files
+ * have been parsed with deferSuperResolution: true. Unresolved refs are
+ * collected and returned — caller decides whether to throw or warn.
+ *
+ * Tracks an inherited context package while walking so children whose own
+ * `package` is unset (e.g., fields inside an object) still resolve against
+ * the parent's package — matching the parser's eager-resolution semantics.
+ *
+ * Idempotent: nodes that already have superResolved set are skipped.
+ */
+export declare function resolveDeferredSupers(root: MetaData): DeferredSuperFailure[];
+//# sourceMappingURL=super-resolve.d.ts.map

package/dist/super-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"super-resolve.d.ts","sourceRoot":"","sources":["../src/super-resolve.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAwBtD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,QAAQ,GACb,QAAQ,GAAG,SAAS,CAsCtB;AAMD,MAAM,WAAW,oBAAoB;IACnC,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,QAAQ,GAAG,oBAAoB,EAAE,CAkB5E"}

package/dist/super-resolve.js

@@ -0,0 +1,124 @@
+// super reference resolution — package navigation helpers
+//
+// Reference syntax (Java metaobjects-core conventions):
+//   Bare name       "Fruit"            → resolve in contextPackage, then root fallback
+//   Absolute        "::fishstore::Fish" → strip leading ::, walk from root
+//   Relative parent "..::common::id"   → up one package level, then resolve "common::id"
+//   Multi-level     "..::..::shared::User" → up two levels, then resolve "shared::User"
+//   Same-package    "common::id"       → try contextPackage prepend first, then root-rooted
+//
+// Super resolution is now IMMEDIATE during parse (Java behavior).
+// This module provides only the lookup helper; the parser calls it inline.
+// The old resolveSupers() multi-pass walker has been deleted.
+import { PACKAGE_SEPARATOR, PACKAGE_PARENT } from "./shared/structural.js";
+// ---------------------------------------------------------------------------
+// Tree search helper
+// ---------------------------------------------------------------------------
+/**
+ * Recursively searches the tree for a node whose fqn() matches.
+ * Returns the first match, or undefined.
+ */
+function findInTree(root, fqn) {
+    if (root.fqn() === fqn)
+        return root;
+    for (const child of root.ownChildren()) {
+        const found = findInTree(child, fqn);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Reference parsing & resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a single super reference string against a tree.
+ *
+ * Called by the parser IMMEDIATELY when a node with a `super` key is created,
+ * against the loader's accumulating root (intoRoot). Java semantics: if the
+ * ref cannot be resolved, the parser throws ParseError.
+ *
+ * @param ref - The raw super reference (e.g., "Fruit", "::pkg::Name", "..::common::id")
+ * @param contextPackage - The package of the model whose super is being resolved
+ * @param root - The root MetaData of the accumulating tree to search within
+ * @returns The resolved MetaData, or undefined if the reference cannot be resolved
+ */
+export function resolveSuperRef(ref, contextPackage, root) {
+    // -------------------------------------------------------------------------
+    // 1. Absolute reference: leading "::"
+    // -------------------------------------------------------------------------
+    if (ref.startsWith(PACKAGE_SEPARATOR)) {
+        const absolutePath = ref.slice(PACKAGE_SEPARATOR.length);
+        return findInTree(root, absolutePath);
+    }
+    // -------------------------------------------------------------------------
+    // 2. Relative reference: one or more leading "..::"
+    // -------------------------------------------------------------------------
+    if (ref.startsWith(PACKAGE_PARENT + PACKAGE_SEPARATOR)) {
+        const parts = ref.split(PACKAGE_SEPARATOR);
+        let levels = 0;
+        while (levels < parts.length && parts[levels] === PACKAGE_PARENT) {
+            levels++;
+        }
+        const pkgParts = contextPackage !== "" ? contextPackage.split(PACKAGE_SEPARATOR) : [];
+        const remainder = parts.slice(levels);
+        if (pkgParts.length < levels || remainder.length === 0) {
+            return undefined;
+        }
+        const allParts = [...pkgParts.slice(0, pkgParts.length - levels), ...remainder];
+        return findInTree(root, allParts.join(PACKAGE_SEPARATOR));
+    }
+    // -------------------------------------------------------------------------
+    // 3. Bare name OR same-package shorthand (contains "::" but no leading
+    //    "::" or "..::"): try contextPackage prepend first, then root-rooted.
+    // -------------------------------------------------------------------------
+    if (contextPackage !== "") {
+        const found = findInTree(root, `${contextPackage}${PACKAGE_SEPARATOR}${ref}`);
+        if (found !== undefined)
+            return found;
+    }
+    return findInTree(root, ref);
+}
+/**
+ * Walk the tree and resolve every node's superRef against the full root.
+ * Used by Loader.loadJsonStrings as a second pass after all input files
+ * have been parsed with deferSuperResolution: true. Unresolved refs are
+ * collected and returned — caller decides whether to throw or warn.
+ *
+ * Tracks an inherited context package while walking so children whose own
+ * `package` is unset (e.g., fields inside an object) still resolve against
+ * the parent's package — matching the parser's eager-resolution semantics.
+ *
+ * Idempotent: nodes that already have superResolved set are skipped.
+ */
+export function resolveDeferredSupers(root) {
+    const failures = [];
+    walk(root, "", (node, ctxPkg) => {
+        if (node.superRef === undefined)
+            return;
+        if (node.superResolved !== undefined)
+            return;
+        const effectivePkg = node.package ?? ctxPkg;
+        const target = resolveSuperRef(node.superRef, effectivePkg, root);
+        if (target !== undefined) {
+            try {
+                node.setSuperResolved(target);
+            }
+            catch {
+                // Frozen — ignore; the loader should resolve before freeze.
+            }
+        }
+        else {
+            failures.push({ nodeFqn: node.fqn(), ref: node.superRef });
+        }
+    });
+    return failures;
+}
+function walk(node, ctxPkg, visit) {
+    visit(node, ctxPkg);
+    const nextCtx = node.package ?? ctxPkg;
+    for (const child of node.ownChildren()) {
+        walk(child, nextCtx, visit);
+    }
+}
+//# sourceMappingURL=super-resolve.js.map

package/dist/super-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"super-resolve.js","sourceRoot":"","sources":["../src/super-resolve.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@metaobjectsdev/metadata",
+  "version": "0.5.0-rc.1",
+  "description": "Metamodel loader, types, and constants for the MetaObjects standard.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./core": {
+      "bun": "./src/core/index.ts",
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "conformance:mutation": "stryker run"
+  },
+  "license": "Apache-2.0",
+  "author": "Doug Mealing <doug@dougmealing.com>",
+  "homepage": "https://metaobjects.dev",
+  "bugs": {
+  "url": "https://github.com/metaobjectsdev/metaobjects/issues"
+},
+"repository": {
+  "type": "git",
+  "url": "https://github.com/metaobjectsdev/metaobjects.git",
+  "directory": "server/typescript/packages/metadata"
+},
+"keywords": ["metaobjects", "metadata", "schema", "loader", "typescript"],
+"publishConfig": {
+"access": "public"
+},
+"dependencies": {
+  "yaml": "^2.9.0"
+},
+"devDependencies": {
+  "@metaobjectsdev/conformance": "0.1.0",
+  "@stryker-mutator/core": "^9.6.1",
+  "bun-types": "latest",
+  "typescript": "^5.6.0"
+}
+}

package/src/attr-class-map.ts

@@ -0,0 +1,64 @@
+// attr-class-map — dependency-free registry mapping each attr subtype to its
+// concrete MetaAttr (sub)class.
+//
+// Why a registry (and not a static Map literal of class references): MetaData
+// (the base of every node, including MetaAttr) must resolve an attr subclass in
+// setAttr. If MetaData imported a module that imported the MetaAttr subclasses,
+// that closes a module-eval cycle (meta-data → <map> → meta-attr → meta-data)
+// and the `class MetaAttr extends MetaData` clause runs before MetaData is
+// initialized (TDZ). To break it, this module imports NOTHING from the meta
+// tree: each subclass registers ITSELF here (one self-registration line per
+// subclass — the Open-Closed seam), and meta-data.ts reads back through this
+// dependency-free leaf.
+
+import type { TypeId } from "./registry.js";
+import type { MetaData } from "./shared/meta-data.js";
+import type { MetaAttr } from "./core/attr/meta-attr.js";
+
+/** A general node constructor — kept assignable from AttrConstructor. */
+export type NodeConstructor = new (typeId: TypeId, name: string) => MetaData;
+
+/** A MetaAttr (sub)class constructor — narrower than NodeConstructor so callers
+ *  can read `.dataType` off a probe instance and store the result in a
+ *  Map<string, MetaAttr>. Assignable to NodeConstructor since MetaAttr extends
+ *  MetaData. MetaAttr is imported type-only here so this module stays free of
+ *  any meta-tree value import (type imports are erased — no eval cycle). */
+export type AttrConstructor = new (typeId: TypeId, name: string) => MetaAttr;
+
+/** Subtype → concrete attr subclass. Populated by each subclass at module load
+ *  via registerAttrClass. The base MetaAttr is the fallback for unmapped
+ *  (scalar/string) subtypes — see attrClassFor. */
+export const ATTR_CLASS_MAP = new Map<string, AttrConstructor>();
+
+/** Fallback constructor for unmapped subtypes (the base MetaAttr). Registered
+ *  by meta-attr.ts at load so attrClassFor never returns undefined. */
+let fallbackAttrClass: AttrConstructor | undefined;
+
+/** Register a subtype → subclass mapping. Called by each attr subclass module
+ *  at load time (`registerAttrClass(ATTR_SUBTYPE_X, XAttr)`). */
+export function registerAttrClass(subType: string, ctor: AttrConstructor): void {
+  ATTR_CLASS_MAP.set(subType, ctor);
+}
+
+/** Register the base MetaAttr as the fallback for unmapped subtypes. Called once
+ *  by meta-attr.ts at load. */
+export function registerFallbackAttrClass(ctor: AttrConstructor): void {
+  fallbackAttrClass = ctor;
+}
+
+/** The concrete MetaAttr subclass for an attr subtype (default base MetaAttr).
+ *  Used by MetaData.setAttr to materialize an undeclared attr as the right
+ *  class, and by core-types to register the subtype's TypeDefinition. */
+export function attrClassFor(subType: string): AttrConstructor {
+  const ctor = ATTR_CLASS_MAP.get(subType) ?? fallbackAttrClass;
+  if (ctor === undefined) {
+    throw new Error(
+      `Attr classes are not registered (no fallback set, and no class for subType '${subType}'). ` +
+        `The MetaAttr subclasses self-register as a module side-effect; a deep direct import that ` +
+        `bypasses the package entry can run MetaData.setAttr before they load. ` +
+        `Import the package entry ("@metaobjectsdev/metadata") or register the core types ` +
+        `(registerCoreTypes) before constructing/loading metadata.`,
+    );
+  }
+  return ctor;
+}

package/src/attr-schema-validate.ts

@@ -0,0 +1,134 @@
+// Phase A3 — attribute-schema validation pass.
+//
+// Consumes the per-(type, subType) attribute schema populated in core-types.ts
+// (Phase A2). For each node in the loaded typed tree, looks up
+// registry.attrsOf(node.type, node.subType) and checks the node's OWN
+// @-attributes against that schema:
+//
+//   1. Required attrs present       — every AttrSchema with required:true must
+//                                      have a matching attr on the node.
+//   2. Declared attrs well-typed    — for each @-attr ON the node that IS in the
+//                                      schema, its value must satisfy the
+//                                      MetaAttr instance's own validateValue.
+//   3. allowedValues honored        — declared attrs with a non-empty
+//                                      allowedValues set must hold a member value.
+//   4. Undeclared attrs             — NOT an error, NOT a warning (open policy).
+//
+// `default` values are NOT auto-applied — A3 is pure validation, not mutation.
+//
+// Checks 2+3 dispatch to the materialized MetaAttr instance: each attr is a
+// MetaAttr that owns validateValue(value): ValueError[] (resolved by its
+// subType, which the parser chose from the declared valueType). The central
+// value-shape helper + the per-shape subtype sets are gone — value-shape
+// knowledge now lives on the instance. The pass maps each ValueError to a
+// ParseError with the unchanged ERR_BAD_ATTR_VALUE code, so conformance
+// fixtures stay green.
+//
+// Modeled on src/subtype-rules.ts: a recursive walk producing an
+// { errors, warnings } result. All A3 findings are ERRORS; warnings stays [].
+
+import type { MetaData } from "./shared/meta-data.js";
+import { ParseError } from "./errors.js";
+import type { AttrSchema, TypeRegistry } from "./registry.js";
+
+export interface AttrSchemaValidationResult {
+  errors: ParseError[];
+  warnings: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+
+export function validateAttrSchema(
+  root: MetaData,
+  registry: TypeRegistry,
+): AttrSchemaValidationResult {
+  const errors: ParseError[] = [];
+  walk(root, registry, errors);
+  return { errors, warnings: [] };
+}
+
+function walk(
+  node: MetaData,
+  registry: TypeRegistry,
+  errors: ParseError[],
+): void {
+  validateNode(node, registry, errors);
+  for (const child of node.ownChildren()) {
+    walk(child, registry, errors);
+  }
+}
+
+/** A node label for error messages, e.g. `origin.aggregate 'weekCount'`. */
+function nodeLabel(node: MetaData): string {
+  const head = `${node.type}.${node.subType}`;
+  return node.name !== "" ? `${head} '${node.name}'` : head;
+}
+
+function validateNode(
+  node: MetaData,
+  registry: TypeRegistry,
+  errors: ParseError[],
+): void {
+  const schema = registry.attrsOf(node.type, node.subType);
+  if (schema.length === 0) return;
+
+  // Index the schema by attr name for the declared-attr checks below.
+  const byName = new Map<string, AttrSchema>();
+  for (const spec of schema) byName.set(spec.name, spec);
+
+  // --- Check 1: required attrs present ---
+  //
+  // Use attrs() (own + inherited via extends:) to determine presence.
+  // A node that legitimately inherits a required attr from its super must NOT be
+  // flagged as missing it — inherited attrs count as satisfying the requirement.
+  // Contrast with Checks 2+3 below, which iterate own attrs only: inherited attrs
+  // were already validated on the node that declared them, so re-checking would
+  // double-report. This mirrors the effective-vs-own split in subtype-rules.ts.
+  const effective = node.attrs();
+  for (const spec of schema) {
+    if (spec.required && !effective.has(spec.name)) {
+      errors.push(
+        new ParseError(
+          `${nodeLabel(node)} is missing required attribute '@${spec.name}'`,
+          { code: "ERR_MISSING_REQUIRED_ATTR" },
+        ),
+      );
+    }
+  }
+
+  // --- Checks 2 + 3: declared attrs on the node are well-typed + in range ---
+  for (const inst of node.ownMetaAttrs()) {
+    const spec = byName.get(inst.name);
+    if (spec === undefined) continue; // undeclared attr → open policy: ignore.
+    const value = inst.value;
+    if (value === undefined) continue;
+
+    // Check 2: the instance validates its own value shape. When the declared
+    // valueType is absent (e.g. @default), skip — any AttrValue is valid.
+    if (spec.valueType !== undefined) {
+      const valueErrors = inst.validateValue(value);
+      if (valueErrors.length > 0) {
+        for (const ve of valueErrors) {
+          errors.push(new ParseError(`${nodeLabel(node)} ${ve.message}`, { code: "ERR_BAD_ATTR_VALUE" }));
+        }
+        continue; // type wrong → skip allowedValues
+      }
+    }
+
+    // Check 3: allowedValues membership (unchanged).
+    if (spec.allowedValues !== undefined && spec.allowedValues.length > 0) {
+      if (!spec.allowedValues.includes(value)) {
+        errors.push(
+          new ParseError(
+            `${nodeLabel(node)} attribute '@${inst.name}' has value ` +
+              `'${String(value)}' which is not one of the allowed values: ` +
+              `${spec.allowedValues.map((v) => String(v)).join(", ")}`,
+            { code: "ERR_BAD_ATTR_VALUE" },
+          ),
+        );
+      }
+    }
+  }
+}

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

@@ -0,0 +1,31 @@
+// Attr concern constants — subtypes for the attr.* type family.
+
+import { SUBTYPE_BASE } from "../../shared/base-types.js";
+
+// ---------------------------------------------------------------------------
+// Attr subtypes (10)
+// ---------------------------------------------------------------------------
+
+export const ATTR_SUBTYPE_STRING = "string";
+export const ATTR_SUBTYPE_INT = "int";
+export const ATTR_SUBTYPE_LONG = "long";
+export const ATTR_SUBTYPE_DOUBLE = "double";
+export const ATTR_SUBTYPE_BOOLEAN = "boolean";
+export const ATTR_SUBTYPE_CLASS = "class";
+export const ATTR_SUBTYPE_PROPERTIES = "properties";
+export const ATTR_SUBTYPE_STRINGARRAY = "stringarray";
+export const ATTR_SUBTYPE_FILTER = "filter";
+
+export const ATTR_SUBTYPES = [
+  SUBTYPE_BASE,
+  ATTR_SUBTYPE_STRING,
+  ATTR_SUBTYPE_INT,
+  ATTR_SUBTYPE_LONG,
+  ATTR_SUBTYPE_DOUBLE,
+  ATTR_SUBTYPE_BOOLEAN,
+  ATTR_SUBTYPE_CLASS,
+  ATTR_SUBTYPE_PROPERTIES,
+  ATTR_SUBTYPE_STRINGARRAY,
+  ATTR_SUBTYPE_FILTER,
+] as const;
+export type AttrSubType = (typeof ATTR_SUBTYPES)[number];

package/src/core/attr/meta-attr-filter.ts

@@ -0,0 +1,67 @@
+// FilterAttr — attr subtype `filter`. Object-shaped value; desugars a preset
+// filter to canonical `{ field: { op: value } }` form (scalar→eq, array→in,
+// null→isNull; or/and recurse). Moved here from parser-core.ts
+// `normalizeFilterAttr` / `desugarFilterObject` / `desugarClause`.
+
+import { MetaAttr, type ValueError, runtimeTypeName } from "./meta-attr.js";
+import { type AttrValue, type AttrObject, type AttrJson } from "../../shared/meta-data.js";
+import { DATA_TYPE_OBJECT, type DataType } from "../../data-type.js";
+import { ATTR_SUBTYPE_FILTER } from "./attr-constants.js";
+import {
+  FILTER_OP_EQ,
+  FILTER_OP_IN,
+  FILTER_OP_IS_NULL,
+  FILTER_COMPOSE_OR,
+  FILTER_COMPOSE_AND,
+} from "../query/query-constants.js";
+import { registerAttrClass } from "../../attr-class-map.js";
+
+export class FilterAttr extends MetaAttr {
+  override get dataType(): DataType {
+    return DATA_TYPE_OBJECT;
+  }
+
+  override coerce(raw: unknown): AttrValue {
+    // Stored verbatim: an object is the canonical shape; a non-object (e.g. a
+    // legacy JSON string) is passed through unchanged so validateValue rejects it.
+    return raw as AttrValue;
+  }
+
+  override desugar(value: AttrValue): AttrValue {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+    return desugarFilterObject(value as AttrObject);
+  }
+
+  override validateValue(value: AttrValue): ValueError[] {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? []
+      : [{ message: `attribute '@${this.name}' must be of type 'filter' but got ${runtimeTypeName(value)}` }];
+  }
+}
+
+function desugarFilterObject(filter: AttrObject): AttrObject {
+  const out: Record<string, AttrJson> = {};
+  for (const [key, raw] of Object.entries(filter)) {
+    if (key === FILTER_COMPOSE_OR || key === FILTER_COMPOSE_AND) {
+      out[key] = Array.isArray(raw)
+        ? raw.map((sub: AttrJson) =>
+            typeof sub === "object" && sub !== null && !Array.isArray(sub)
+              ? desugarFilterObject(sub as AttrObject)
+              : sub,
+          )
+        : (raw as AttrJson);
+      continue;
+    }
+    out[key] = desugarClause(raw);
+  }
+  return out;
+}
+
+function desugarClause(raw: AttrJson): AttrObject {
+  if (raw === null) return { [FILTER_OP_IS_NULL]: true };
+  if (Array.isArray(raw)) return { [FILTER_OP_IN]: raw };
+  if (typeof raw === "object") return raw as AttrObject;
+  return { [FILTER_OP_EQ]: raw };
+}
+
+registerAttrClass(ATTR_SUBTYPE_FILTER, FilterAttr);