feat(python): relationship @onDelete/@onUpdate + REFERENTIAL_ACTIONS

Adds the cross-language referential-action vocabulary to the relationship
subtypes (association, aggregation, composition):

  - REFERENTIAL_ACTIONS = ("cascade", "set-null", "restrict", "no-action")
    — kebab-case, matches the TS migrate-ts FkAction set byte-for-byte.
  - RELATIONSHIP_ATTR_ON_DELETE = "onDelete"
  - RELATIONSHIP_ATTR_ON_UPDATE = "onUpdate"
  - ON_DELETE_DEFAULT_BY_SUBTYPE: composition=cascade, aggregation=set-null,
    association=restrict (applied at consumption time, not in validation).
  - ON_UPDATE_DEFAULT = "cascade" (subtype-independent).

Registered as optional AttrSchemas on every relationship subtype with the
allowed_values gate. Out-of-set values → ERR_BAD_ATTR_VALUE.

MetaRelationship gains on_delete() / on_update() accessors (return None when
not authored, so callers can apply per-subtype defaults), plus typed accessors
for the existing @objectref / @Cardinality / @joinEntity / @joinFields attrs.

Tests: +10 in tests/unit/test_relationship_referential_actions.py covering
constants, accessors, and the loader allowed-values gate for both attrs.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: dmealing

server/python/src/metaobjects/core_types.py

@@ -29,7 +29,12 @@
 from .meta.core.object.meta_object import MetaObject
 from .meta.core.object.object_constants import OBJECT_SUBTYPES
 from .meta.core.relationship.meta_relationship import MetaRelationship
-from .meta.core.relationship.relationship_constants import RELATIONSHIP_SUBTYPES
+from .meta.core.relationship.relationship_constants import (
+    REFERENTIAL_ACTIONS,
+    RELATIONSHIP_ATTR_ON_DELETE,
+    RELATIONSHIP_ATTR_ON_UPDATE,
+    RELATIONSHIP_SUBTYPES,
+)
 from .meta.meta_root import MetaRoot
 from .meta.persistence.origin.meta_origin import MetaOrigin
 from .meta.persistence.origin.origin_constants import (
@@ -215,13 +220,31 @@ def _register_subtypes(
     )
 )
 
-# relationship.* (base, association, aggregation, composition)
+# relationship.* (base, association, aggregation, composition).
+# @onDelete / @onUpdate are validated against REFERENTIAL_ACTIONS — kebab-case
+# values (cascade / set-null / restrict / no-action). Defaults derive from the
+# relationship subtype at consumption time, not at validation time.
+_RELATIONSHIP_ATTRS = [
+    AttrSchema(
+        name=RELATIONSHIP_ATTR_ON_DELETE,
+        value_type=ATTR_SUBTYPE_STRING,
+        required=False,
+        allowed_values=REFERENTIAL_ACTIONS,
+    ),
+    AttrSchema(
+        name=RELATIONSHIP_ATTR_ON_UPDATE,
+        value_type=ATTR_SUBTYPE_STRING,
+        required=False,
+        allowed_values=REFERENTIAL_ACTIONS,
+    ),
+]
 _register_subtypes(
     core_provider,
     TYPE_RELATIONSHIP,
     RELATIONSHIP_SUBTYPES,
     factory=MetaRelationship,
     child_rules=[ChildRule(TYPE_ATTR, "*")],
+    attrs=_RELATIONSHIP_ATTRS,
 )
 
 # source.* — base (no attrs) + rdb (paradigm subtype with @table/@kind/@role/@schema).

server/python/src/metaobjects/meta/core/relationship/meta_relationship.py

@@ -2,7 +2,48 @@
 from __future__ import annotations
 
 from ...meta_data import MetaData
+from .relationship_constants import (
+    RELATIONSHIP_ATTR_CARDINALITY,
+    RELATIONSHIP_ATTR_JOIN_ENTITY,
+    RELATIONSHIP_ATTR_JOIN_FIELDS,
+    RELATIONSHIP_ATTR_OBJECT_REF,
+    RELATIONSHIP_ATTR_ON_DELETE,
+    RELATIONSHIP_ATTR_ON_UPDATE,
+)
 
 
 class MetaRelationship(MetaData):
-    pass
+    """A relationship.* node. Accessors mirror the TS reference / Java port —
+    own-attr reads; defaults for @onDelete/@onUpdate are resolved at consumption
+    time (codegen / migration) not here."""
+
+    def cardinality(self) -> str | None:
+        v = self.attr(RELATIONSHIP_ATTR_CARDINALITY)
+        return v if isinstance(v, str) else None
+
+    def object_ref(self) -> str | None:
+        """FQN of the target object (e.g., ``"acme::vehicle::Car"``)."""
+        v = self.attr(RELATIONSHIP_ATTR_OBJECT_REF)
+        return v if isinstance(v, str) else None
+
+    def join_entity(self) -> str | None:
+        """Join-table entity name for N:M relationships."""
+        v = self.attr(RELATIONSHIP_ATTR_JOIN_ENTITY)
+        return v if isinstance(v, str) else None
+
+    def join_fields(self) -> list[str]:
+        """Join-table column names for N:M relationships."""
+        v = self.attr(RELATIONSHIP_ATTR_JOIN_FIELDS)
+        return list(v) if isinstance(v, list) else []
+
+    def on_delete(self) -> str | None:
+        """Referential action on parent delete. ``None`` when not explicitly set
+        (default derives from subtype at consumption time)."""
+        v = self.attr(RELATIONSHIP_ATTR_ON_DELETE)
+        return v if isinstance(v, str) and v else None
+
+    def on_update(self) -> str | None:
+        """Referential action on key update. ``None`` when not explicitly set
+        (default: cascade at consumption time)."""
+        v = self.attr(RELATIONSHIP_ATTR_ON_UPDATE)
+        return v if isinstance(v, str) and v else None

server/python/src/metaobjects/meta/core/relationship/relationship_constants.py

@@ -18,3 +18,22 @@
 RELATIONSHIP_ATTR_PARENT_FIELD = "parentField"
 RELATIONSHIP_ATTR_JOIN_ENTITY = "joinEntity"
 RELATIONSHIP_ATTR_JOIN_FIELDS = "joinFields"
+
+# --- Referential action attrs (@onDelete / @onUpdate) ----------------------
+
+RELATIONSHIP_ATTR_ON_DELETE = "onDelete"
+RELATIONSHIP_ATTR_ON_UPDATE = "onUpdate"
+
+# Canonical cross-language referential-action set (kebab-case, no "setDefault").
+# MUST equal TS migrate-ts FkAction; mirrors Java REFERENTIAL_ACTIONS.
+REFERENTIAL_ACTIONS = ("cascade", "set-null", "restrict", "no-action")
+
+# Default @onDelete per relationship subtype (rollout-decided defaults).
+ON_DELETE_DEFAULT_BY_SUBTYPE: dict[str, str] = {
+    RELATIONSHIP_SUBTYPE_COMPOSITION: "cascade",
+    RELATIONSHIP_SUBTYPE_AGGREGATION: "set-null",
+    RELATIONSHIP_SUBTYPE_ASSOCIATION: "restrict",
+}
+
+# Default @onUpdate (subtype-independent).
+ON_UPDATE_DEFAULT = "cascade"

server/python/tests/unit/test_relationship_referential_actions.py

@@ -0,0 +1,162 @@
+"""Unit tests for relationship @onDelete / @onUpdate (referential actions).
+
+Tier-1 cross-language contract:
+  - Attr names: 'onDelete', 'onUpdate'
+  - Action value-set: ('cascade', 'set-null', 'restrict', 'no-action') — kebab-case
+  - Per-subtype @onDelete defaults: composition→cascade, aggregation→set-null,
+    association→restrict (defaults applied at consumption time; the loader does
+    not synthesize them, only validates explicit values).
+  - @onUpdate default: cascade (subtype-independent).
+
+The loader rejects any value outside the action set with ERR_BAD_ATTR_VALUE
+(implemented via the allowed_values schema in core_types.py — single source of
+truth).
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from metaobjects.core_types import core_provider
+from metaobjects.loader.meta_data_loader import load_directory
+from metaobjects.meta.core.relationship.meta_relationship import MetaRelationship
+from metaobjects.meta.core.relationship.relationship_constants import (
+    ON_DELETE_DEFAULT_BY_SUBTYPE,
+    ON_UPDATE_DEFAULT,
+    REFERENTIAL_ACTIONS,
+    RELATIONSHIP_ATTR_ON_DELETE,
+    RELATIONSHIP_ATTR_ON_UPDATE,
+    RELATIONSHIP_SUBTYPE_AGGREGATION,
+    RELATIONSHIP_SUBTYPE_ASSOCIATION,
+    RELATIONSHIP_SUBTYPE_COMPOSITION,
+)
+from metaobjects.shared.base_types import TYPE_RELATIONSHIP
+
+
+# ---------------------------------------------------------------------------
+# Constants — Tier-1 cross-language contract
+# ---------------------------------------------------------------------------
+
+
+def test_referential_attr_name_constants() -> None:
+    """Attr names must equal TS + Java byte-for-byte."""
+    assert RELATIONSHIP_ATTR_ON_DELETE == "onDelete"
+    assert RELATIONSHIP_ATTR_ON_UPDATE == "onUpdate"
+
+
+def test_referential_actions_value_set() -> None:
+    """Action set must be kebab-case (no 'setDefault'); order pins migrate-ts FkAction."""
+    assert REFERENTIAL_ACTIONS == ("cascade", "set-null", "restrict", "no-action")
+
+
+def test_on_delete_defaults_by_subtype() -> None:
+    """Per-subtype @onDelete defaults (consumption-time, not validation-time)."""
+    assert ON_DELETE_DEFAULT_BY_SUBTYPE[RELATIONSHIP_SUBTYPE_COMPOSITION] == "cascade"
+    assert ON_DELETE_DEFAULT_BY_SUBTYPE[RELATIONSHIP_SUBTYPE_AGGREGATION] == "set-null"
+    assert ON_DELETE_DEFAULT_BY_SUBTYPE[RELATIONSHIP_SUBTYPE_ASSOCIATION] == "restrict"
+
+
+def test_on_update_default_is_cascade() -> None:
+    """@onUpdate default is subtype-independent: cascade."""
+    assert ON_UPDATE_DEFAULT == "cascade"
+
+
+# ---------------------------------------------------------------------------
+# Accessors
+# ---------------------------------------------------------------------------
+
+
+def test_on_delete_accessor_none_when_unset() -> None:
+    """meta-relationship.on_delete() returns None when not authored (default applied later)."""
+    r = MetaRelationship(TYPE_RELATIONSHIP, RELATIONSHIP_SUBTYPE_COMPOSITION, "items")
+    assert r.on_delete() is None
+    assert r.on_update() is None
+
+
+def test_on_delete_accessor_returns_authored_value() -> None:
+    r = MetaRelationship(TYPE_RELATIONSHIP, RELATIONSHIP_SUBTYPE_ASSOCIATION, "owner")
+    r.set_attr(RELATIONSHIP_ATTR_ON_DELETE, "cascade", sub_type="string")
+    r.set_attr(RELATIONSHIP_ATTR_ON_UPDATE, "no-action", sub_type="string")
+    assert r.on_delete() == "cascade"
+    assert r.on_update() == "no-action"
+
+
+# ---------------------------------------------------------------------------
+# Loader integration — allowed-values gate
+# ---------------------------------------------------------------------------
+
+
+def _load(doc: dict) -> list[str]:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        path = os.path.join(tmpdir, "meta.test.json")
+        Path(path).write_text(json.dumps(doc))
+        result = load_directory(tmpdir, providers=[core_provider])
+        return [e.code.name for e in result.errors]
+
+
+def _two_entity_doc(child_attrs: dict[str, str]) -> dict:
+    """A two-entity doc: Program -> Week composition with overridable referential actions."""
+    return {
+        "metadata.root": {
+            "package": "acme",
+            "children": [
+                {
+                    "object.entity": {
+                        "name": "Program",
+                        "children": [
+                            {"source.rdb": {"@table": "programs"}},
+                            {"field.long": {"name": "id"}},
+                            {"identity.primary": {"@fields": "id"}},
+                            {
+                                "relationship.composition": {
+                                    "name": "weeks",
+                                    "@objectRef": "Week",
+                                    "@cardinality": "one-to-many",
+                                    **{f"@{k}": v for k, v in child_attrs.items()},
+                                }
+                            },
+                        ],
+                    }
+                },
+                {
+                    "object.entity": {
+                        "name": "Week",
+                        "children": [
+                            {"source.rdb": {"@table": "weeks"}},
+                            {"field.long": {"name": "id"}},
+                            {"field.long": {"name": "programId"}},
+                            {"identity.primary": {"@fields": "id"}},
+                        ],
+                    }
+                },
+            ],
+        }
+    }
+
+
+def test_valid_on_delete_action_loads_ok() -> None:
+    """Every member of REFERENTIAL_ACTIONS is accepted as @onDelete."""
+    for action in REFERENTIAL_ACTIONS:
+        codes = _load(_two_entity_doc({"onDelete": action}))
+        assert "ERR_BAD_ATTR_VALUE" not in codes, f"{action!r} should be valid; got {codes}"
+
+
+def test_valid_on_update_action_loads_ok() -> None:
+    """Every member of REFERENTIAL_ACTIONS is accepted as @onUpdate."""
+    for action in REFERENTIAL_ACTIONS:
+        codes = _load(_two_entity_doc({"onUpdate": action}))
+        assert "ERR_BAD_ATTR_VALUE" not in codes, f"{action!r} should be valid; got {codes}"
+
+
+def test_invalid_on_delete_rejected() -> None:
+    """Out-of-set @onDelete value → ERR_BAD_ATTR_VALUE."""
+    codes = _load(_two_entity_doc({"onDelete": "setDefault"}))
+    assert "ERR_BAD_ATTR_VALUE" in codes, f"Expected ERR_BAD_ATTR_VALUE; got {codes}"
+
+
+def test_invalid_on_update_rejected() -> None:
+    """Out-of-set @onUpdate value → ERR_BAD_ATTR_VALUE."""
+    codes = _load(_two_entity_doc({"onUpdate": "RESTRICT"}))  # wrong case — should reject
+    assert "ERR_BAD_ATTR_VALUE" in codes, f"Expected ERR_BAD_ATTR_VALUE; got {codes}"