@metaobjectsdev/metadata 0.9.0 → 0.11.0-rc.1

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-constants.ts

@@ -3,7 +3,7 @@
 import { SUBTYPE_BASE } from "../../shared/base-types.js";
 
 // ---------------------------------------------------------------------------
-// Validator subtypes (6)
+// Validator subtypes (10)
 // ---------------------------------------------------------------------------
 
 export const VALIDATOR_SUBTYPE_REQUIRED = "required";
@@ -11,6 +11,11 @@ export const VALIDATOR_SUBTYPE_LENGTH = "length";
 export const VALIDATOR_SUBTYPE_REGEX = "regex";
 export const VALIDATOR_SUBTYPE_NUMERIC = "numeric";
 export const VALIDATOR_SUBTYPE_ARRAY = "array";
+// Cross-field validators — entity-scoped, reference sibling fields by name.
+export const VALIDATOR_SUBTYPE_COMPARISON = "comparison";
+export const VALIDATOR_SUBTYPE_REQUIRED_WHEN = "requiredWhen";
+export const VALIDATOR_SUBTYPE_PRESENT_IFF = "presentIff";
+export const VALIDATOR_SUBTYPE_AT_LEAST_ONE = "atLeastOne";
 
 export const VALIDATOR_SUBTYPES = [
   SUBTYPE_BASE,
@@ -19,6 +24,10 @@ export const VALIDATOR_SUBTYPES = [
   VALIDATOR_SUBTYPE_REGEX,
   VALIDATOR_SUBTYPE_NUMERIC,
   VALIDATOR_SUBTYPE_ARRAY,
+  VALIDATOR_SUBTYPE_COMPARISON,
+  VALIDATOR_SUBTYPE_REQUIRED_WHEN,
+  VALIDATOR_SUBTYPE_PRESENT_IFF,
+  VALIDATOR_SUBTYPE_AT_LEAST_ONE,
 ] as const;
 export type ValidatorSubType = (typeof VALIDATOR_SUBTYPES)[number];
 
@@ -29,3 +38,15 @@ export type ValidatorSubType = (typeof VALIDATOR_SUBTYPES)[number];
 export const VALIDATOR_ATTR_PATTERN = "pattern";
 export const VALIDATOR_ATTR_MIN = "min";
 export const VALIDATOR_ATTR_MAX = "max";
+// Cross-field validator attrs (field references by name + operator/value).
+export const VALIDATOR_ATTR_LEFT = "left";
+export const VALIDATOR_ATTR_OP = "op";
+export const VALIDATOR_ATTR_RIGHT = "right";
+export const VALIDATOR_ATTR_FIELD = "field";
+export const VALIDATOR_ATTR_WHEN = "when";
+export const VALIDATOR_ATTR_EQUALS = "equals";
+export const VALIDATOR_ATTR_FIELDS = "fields";
+
+// Comparison operators (@op allowed values) → relational operator.
+export const VALIDATOR_COMPARISON_OPS = ["gt", "gte", "lt", "lte", "ne", "eq"] as const;
+export type ComparisonOp = (typeof VALIDATOR_COMPARISON_OPS)[number];

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

@@ -0,0 +1,262 @@
+// 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)."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "comparison",
+      "description": "Cross-field ordering: requires two sibling fields of the owning entity stand in a relational order (@left @op @right), e.g. current_hp <= max_hp or expires_at > created_at. Entity-scoped; references fields by name. Backends derive the rule (CHECK constraint, cross-field assertion) — no raw expression is stored.",
+      "rules": "@left and @right must name fields of the owning entity. @op is one of gt/gte/lt/lte/ne/eq. The comparison is null-tolerant where the backend's relational operator is (SQL: a NULL operand yields no violation).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "left",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the left-hand field of the owning entity."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "op",
+          "min": 1,
+          "max": 1,
+          "allowedValues": [
+            "gt",
+            "gte",
+            "lt",
+            "lte",
+            "ne",
+            "eq"
+          ],
+          "description": "Relational operator: gt (>), gte (>=), lt (<), lte (<=), ne (<>), eq (=)."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "right",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the right-hand field of the owning entity."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "requiredWhen",
+      "description": "One-directional conditional presence: when the gating field (@when) equals @equals, the target field (@field) must be present (NOT NULL); otherwise @field is unconstrained. Mirrors JSON Schema dependentRequired / Rails validates_presence_of :x, if:. Entity-scoped; references fields by name.",
+      "rules": "@field and @when must name fields of the owning entity. @equals is the gating value, compared against @when's value (rendered per @when's field subtype — boolean true/false, enum/string literal, numeric literal).",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "field",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the field that becomes required when the condition holds."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "when",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the gating field whose value triggers the requirement."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "equals",
+          "min": 1,
+          "max": 1,
+          "description": "The gating value; when @when equals this, @field must be present."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "presentIff",
+      "description": "Biconditional presence: the target field (@field) is present (NOT NULL) if and only if the gating field (@when) equals @equals. Models paired flag/companion-column invariants, e.g. used_at present iff is_used=true. Entity-scoped; references fields by name.",
+      "rules": "@field and @when must name fields of the owning entity. @equals is rendered per @when's field subtype. Stricter than requiredWhen — also forbids @field when the condition is false.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "field",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the field whose presence is governed by the condition."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "when",
+          "min": 1,
+          "max": 1,
+          "description": "Name of the gating field."
+        },
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "equals",
+          "min": 1,
+          "max": 1,
+          "description": "The gating value; @field is present exactly when @when equals this."
+        }
+      ]
+    },
+    {
+      "type": "validator",
+      "subType": "atLeastOne",
+      "description": "Cardinality of presence: at least one of the named fields (@fields) must be present (NOT NULL). Entity-scoped; references fields by name (same @fields-by-name pattern as identity.*).",
+      "rules": "@fields names two or more fields of the owning entity. Satisfied when any one of them is non-null.",
+      "children": [
+        {
+          "type": "attr",
+          "subType": "string",
+          "name": "fields",
+          "isArray": true,
+          "min": 1,
+          "max": 1,
+          "description": "Names of the candidate fields; at least one must be present."
+        }
+      ]
+    }
+  ]
+};