metaobjects 1.0.4__tar.gz → 1.0.5rc3__tar.gz

{metaobjects-1.0.4 → metaobjects-1.0.5rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 1.0.4
+Version: 1.0.5rc3
 Summary: Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port.
 Project-URL: Homepage, https://metaobjects.dev
 Project-URL: Repository, https://github.com/metaobjectsdev/metaobjects

{metaobjects-1.0.4 → metaobjects-1.0.5rc3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "1.0.4"
+version = "1.0.5rc3"
 description = "Cross-language metadata standard: declare typed entities once, generate idiomatic drift-checked code across languages — Python port."
 readme = "README.md"
 requires-python = ">=3.11"

{metaobjects-1.0.4 → metaobjects-1.0.5rc3}/src/metaobjects/apidocs/naming.py

@@ -7,8 +7,10 @@ generators delegate their name computation here, and the
 calling the SAME functions. So the documented name can never drift from the
 emitted name — they are computed once, in one place.
 
-Behaviour-preserving: each function reproduces exactly what the corresponding
-generator used to compute inline (``_snake_case`` / ``_plural_lowercase`` /
+Behaviour-preserving with ONE deliberate exception: :func:`route_path` no longer
+reproduces the old inline ``name.lower() + "s"``, because that spelling diverged
+from the other ports (see its docstring). Every other function reproduces exactly
+what the corresponding generator used to compute inline (``_snake_case`` /
 ``<Name>Repository`` / ``<ENTITY>_FILTER_FIELDS`` / ``parse_<snake>`` /
 ``render_<snake>`` / ``render_<snake>_format`` / ``extract_<snake>`` …). The
 payload-class / payload-module names already lived in
@@ -23,10 +25,11 @@ from metaobjects.codegen.generators.payload_vo_generator import (
     response_class_name,
     response_module_name,
 )
+from metaobjects.naming import to_snake_case
 
 __all__ = [
     "snake_case",
-    "plural_lowercase",
+    "pluralize",
     "model_class_name",
     "router_module_name",
     "repository_class_name",
@@ -64,9 +67,35 @@ def snake_case(name: str) -> str:
     return "".join(out)
 
 
-def plural_lowercase(name: str) -> str:
-    """``Author`` → ``authors``. Cross-port-aligned trivial pluralization."""
-    return name.lower() + "s"
+def _route_snake_case(name: str) -> str:
+    """``PostCategory`` → ``post_category``; ``HTTPServer`` → ``http_server``.
+
+    ACRONYM-AWARE, and deliberately NOT :func:`snake_case`. The trivial variant
+    above inserts a separator before every capital, which is right for a module
+    name but would emit ``h_t_t_p_server`` in a URL. Delegates to
+    :func:`metaobjects.naming.to_snake_case` — the port's acronym-aware loop,
+    documented there as byte-for-byte the other ports' rule (separate when the
+    previous character is lower or a digit, or when it is upper and the NEXT one
+    is lower, so a run of capitals stays together until the final one that
+    begins a word)."""
+    return to_snake_case(name)
+
+
+def pluralize(name: str) -> str:
+    """``post_category`` → ``post_categories``; ``address`` → ``addresses``.
+
+    The cross-port pluralization contract, byte-identical in every port: a word
+    ending ``s``/``x``/``z``/``ch``/``sh`` takes ``es``; a consonant followed by
+    ``y`` becomes ``ies``; anything else takes ``s``. The cross-port
+    byte-identity covers the already-lowercased word :func:`route_path` feeds
+    in — suffix tests here run on a lowercased copy, unlike the JVM port's
+    case-sensitive ones, so mixed-case input may diverge."""
+    lowered = name.lower()
+    if lowered.endswith(("s", "x", "z", "ch", "sh")):
+        return name + "es"
+    if len(name) >= 2 and lowered[-1] == "y" and lowered[-2] not in "aeiou":
+        return name[:-1] + "ies"
+    return name + "s"
 
 
 def model_class_name(obj_name: str) -> str:
@@ -100,9 +129,14 @@ def filter_ops_const(obj_name: str) -> str:
 
 
 def route_path(obj_name: str) -> str:
-    """The default REST base segment — the entity name pluralized + lowercased
-    (cross-port grammar; e.g. ``Author`` → ``authors``)."""
-    return plural_lowercase(obj_name)
+    """The default REST collection segment — the ENTITY NAME ``snake_case``d and
+    then pluralized (``Author`` → ``authors``, ``PostCategory`` →
+    ``post_categories``). Never the physical ``@table``.
+
+    One rule, identical in all five ports. It used to be ``name.lower() + "s"``
+    here, which served ``PostCategory`` at ``/postcategorys``; see
+    ``fixtures/api-contract-conformance/m2m/`` for the scenario that gates it."""
+    return pluralize(_route_snake_case(obj_name))
 
 
 def pk_param(obj_name: str) -> str:
@@ -168,15 +202,14 @@ def extractor_fn(template_name: str) -> str:
 def _pluralize(name: str) -> str:
     """Trivial cross-port pluralization (matches the TS ``pluralize`` /
     ``MetaSource._pluralize``), applied to a PascalCase entity name BEFORE
-    snake-casing (``GameSession`` → ``GameSessions``)."""
+    snake-casing (``GameSession`` → ``GameSessions``).
+
+    Delegates to :func:`pluralize` so this file states the cross-port inflector
+    contract once, not twice; the empty-string guard stays here because it is
+    this finder-naming helper's own contract, not ``pluralize``'s."""
     if not name:
         return name
-    lower = name.lower()
-    if lower.endswith(("s", "x", "z", "ch", "sh")):
-        return name + "es"
-    if len(name) >= 2 and lower[-1] == "y" and lower[-2] not in "aeiou":
-        return name[:-1] + "ies"
-    return name + "s"
+    return pluralize(name)
 
 
 def reverse_finder_fk_segment(fk_field_name: str) -> str:

{metaobjects-1.0.4 → metaobjects-1.0.5rc3}/src/metaobjects/codegen/generators/m2m_codegen.py

@@ -25,8 +25,8 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
+from metaobjects.apidocs.naming import route_path
 from metaobjects.source_resolution import resolve_table_name
-from metaobjects.meta.core.field import field_constants as fc
 from metaobjects.naming import (
     DEFAULT_COLUMN_NAMING,
     apply_column_naming_strategy,
@@ -39,6 +39,8 @@ from metaobjects.meta.core.identity.identity_constants import (
     IDENTITY_SUBTYPE_PRIMARY,
 )
 from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.meta.core.object.object_constants import OBJECT_ATTR_DISCRIMINATOR_VALUE
+from metaobjects.codegen.generators.tph_plan import is_tph_subtype
 from metaobjects.meta.core.relationship.derive_m2m_fields import (
     M2MDerivationError,
     derive_m2m_fields,
@@ -63,6 +65,16 @@ class M2mDescriptor:
     target_column: str
     target_pk_column: str
     symmetric: bool
+    #: The target's OWN ``@discriminatorValue`` when ``@objectRef`` resolves to a
+    #: concrete TPH subtype (FW-8 follow-up; mirrors the TS reference's
+    #: ``targetDiscriminator``) — ``None`` for the overwhelming common case (a
+    #: vanilla, non-TPH target). The target's rows physically live in its
+    #: discriminator base's shared table, so a route generator threads this value
+    #: into the ``find_related_<relation>`` seam as an extra ``target_subtype``
+    #: parameter, structurally handing the consumer's join what it needs to
+    #: filter to just that subtype rather than every row of the shared table.
+    #: Defaulted so existing positional construction (if any) stays valid.
+    target_discriminator: str | None = None
 
 
 def _strip_package(name: str) -> str:
@@ -70,12 +82,6 @@ def _strip_package(name: str) -> str:
     return name[idx + len(PACKAGE_SEP):] if idx >= 0 else name
 
 
-def plural_lowercase(name: str) -> str:
-    """``Person`` → ``persons``. Cross-port-aligned trivial pluralization — the
-    SOURCE URL segment is the entity name pluralized, NOT the physical table."""
-    return name.lower() + "s"
-
-
 def _physical_table(entity: MetaObject, *, relation_context: str) -> str:
     """The entity's physical SQL table name, via the shared
     :func:`~metaobjects.source_resolution.resolve_table_name` resolver.
@@ -168,6 +174,9 @@ def resolve_m2m_descriptors(
     metadata error, surfaced loudly (never silently skipped).
     """
     descriptors: list[M2mDescriptor] = []
+    # The source is *entity* for every relation, so its route segment is
+    # loop-invariant; only the target varies per relation.
+    source_plural = route_path(entity.name)
     for rel in m2m_relationships(entity):
         target_name = _strip_package(rel.object_ref() or "")
         junction_name = _strip_package(rel.through() or "")
@@ -186,13 +195,19 @@ def resolve_m2m_descriptors(
         fields = derive_m2m_fields(rel, entity, meta_index)
         source_fk = _field_named(junction, fields.source_field)
         target_fk = _field_named(junction, fields.target_field)
+        # FW-8 follow-up: the target's rows live in its discriminator base's shared
+        # table when @objectRef resolves to a concrete TPH subtype — @discriminatorValue
+        # is the subtype's OWN value (ADR-0039 sanctioned own, same idiom as tph_plan.py).
+        target_discriminator = (
+            target.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE) if is_tph_subtype(target) else None
+        )
 
         descriptors.append(
             M2mDescriptor(
                 relation_name=rel.name,
                 target_entity=target.name,
-                source_plural=plural_lowercase(entity.name),
-                target_plural=plural_lowercase(target.name),
+                source_plural=source_plural,
+                target_plural=route_path(target.name),
                 junction_table=_physical_table(
                     junction,
                     relation_context=(
@@ -213,6 +228,7 @@ def resolve_m2m_descriptors(
                     column_naming,
                 ),
                 symmetric=rel.symmetric(),
+                target_discriminator=target_discriminator,
             )
         )
     return descriptors

{metaobjects-1.0.4 → metaobjects-1.0.5rc3}/src/metaobjects/codegen/generators/router_generator.py

@@ -34,7 +34,7 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 
-from metaobjects.apidocs.naming import plural_lowercase as _plural_lowercase
+from metaobjects.apidocs.naming import route_path as _route_path
 from metaobjects.apidocs.naming import reverse_finder_fn, reverse_finder_in_fn
 from metaobjects.apidocs.naming import snake_case as _snake_case
 from metaobjects.codegen.constants import generated_header
@@ -193,6 +193,48 @@ def _auto_set_stamp_lines(fields: list[MetaField], comment: str) -> list[str]:
     return lines
 
 
+def _m2m_target_discs(mounts: list[M2mDescriptor]) -> dict[str, set[str | None]]:
+    """Per relation NAME, the set of target discriminators every mount of that
+    name resolves to (``None`` = a non-TPH target) — the ONE decision both the
+    ``find_related_<relation>`` seam signature and every call site derive from.
+    A name mounted more than once (a TPH hierarchy serves it at the base path and
+    under subtype segments, and a subtype may legally SHADOW a base-declared
+    relationship with a target of different TPH-ness) must not let one mount's
+    descriptor decide the seam for all of them."""
+    out: dict[str, set[str | None]] = {}
+    for d in mounts:
+        out.setdefault(d.relation_name, set()).add(d.target_discriminator)
+    return out
+
+
+def _target_subtype_param(discs: set[str | None]) -> str:
+    """FW-8 follow-up: the ``target_subtype`` clause of a
+    ``find_related_<relation>`` Protocol signature, decided per relation NAME
+    from *discs* (:func:`_m2m_target_discs`): empty when no mount of the name
+    targets a TPH subtype (byte-identical output for the overwhelming common
+    case); ``, target_subtype: str`` when every mount does; and
+    ``, target_subtype: str | None`` when only some do — the parameter then
+    threads UNIFORMLY for the name, the non-TPH mounts passing an explicit
+    ``None``, so the seam and every call site agree on arity."""
+    if not discs or discs == {None}:
+        return ""
+    if None in discs:
+        return ", target_subtype: str | None"
+    return ", target_subtype: str"
+
+
+def _target_subtype_arg(d: M2mDescriptor, discs: set[str | None]) -> str:
+    """The call-site counterpart of :func:`_target_subtype_param`, derived from
+    the SAME per-name decision: nothing when the name has no parameter, this
+    mount's resolved ``@discriminatorValue`` literal when it does, and an
+    explicit ``None`` literal for a non-TPH mount of a name that threads it."""
+    if not discs or discs == {None}:
+        return ""
+    if d.target_discriminator is None:
+        return ", None"
+    return f', "{d.target_discriminator}"'
+
+
 def _py_set_literal(names: list[str], *, frozen: bool = False) -> str:
     """A Python set/frozenset literal from field names, matching the generated
     allowlist idiom (one quoted name per line). Empty → ``frozenset()`` / ``set()``."""
@@ -305,6 +347,9 @@ class RouterGenerator:
       create / update / delete), keyed by ``name``.
     * ``_emit_m2m_route(d, snake, pk_param, pk_type, repo_class)`` — one M:N
       traversal route.
+    * ``_emit_tph_m2m_route(d, ..., subtype_expr)`` — one M:N traversal route
+      INSIDE a TPH hierarchy (FW-8), threading the discriminator scope through
+      the subtype-keyed ``find_related_*`` seam.
     * ``render_router(entity, object_index)`` — the whole module (last resort).
 
     Skips entities without a ``source.rdb`` child and read-only kinds
@@ -336,9 +381,11 @@ class RouterGenerator:
             f"    def update(self, id: {pk_type}, dto: Any) -> Any | None: ...",
             f"    def delete(self, id: {pk_type}) -> bool: ...",
         ]
+        discs = _m2m_target_discs(m2m)
         for d in m2m:
             lines.append(
-                f"    def find_related_{d.relation_name}(self, id: {pk_type}) -> list[Any]: ..."
+                f"    def find_related_{d.relation_name}(self, id: {pk_type}"
+                f"{_target_subtype_param(discs[d.relation_name])}) -> list[Any]: ..."
             )
         return lines
 
@@ -493,15 +540,78 @@ class RouterGenerator:
     ) -> list[str]:
         """One M:N traversal route ``GET /{id}/<relationName>`` — a thin pass-through
         to the repository's ``find_related_*`` finder. Override to add filtering /
-        pagination on the traversal."""
+        pagination on the traversal. FW-8 follow-up: when the target resolves to a
+        TPH subtype, the call also carries the resolved ``target_subtype`` literal
+        (see :func:`_target_subtype_arg`) — empty for a vanilla target. A vanilla
+        render mounts a name exactly once, so the name's decision set is the
+        mount's own singleton."""
         return [
             f'@router.get("/{{{pk_param}}}/{d.relation_name}")',
             f"def list_{snake}_{d.relation_name}(",
             f"    {pk_param}: {pk_type},",
             f"    repo: Annotated[{repo_class}, Depends(get_repository)],",
             ") -> list[Any]:",
-            f"    return repo.find_related_{d.relation_name}({pk_param})",
+            f"    return repo.find_related_{d.relation_name}"
+            f"({pk_param}{_target_subtype_arg(d, {d.target_discriminator})})",
+        ]
+
+    def _emit_tph_m2m_route(
+        self,
+        d: M2mDescriptor,
+        *,
+        handler_name: str,
+        route: str,
+        pk_param: str,
+        pk_type: str,
+        repo_class: str,
+        subtype_expr: str,
+        gated: bool,
+        target_discs: set[str | None],
+    ) -> list[str]:
+        """One M:N traversal route INSIDE a TPH hierarchy (FW-8) — ``GET`` *route*
+        delegating to the subtype-keyed ``find_related_<relation>(subtype, id)`` seam,
+        the same discriminator-first shape every other TPH Protocol method already
+        uses (``find_by_id(subtype, id)``, ...).
+
+        *subtype_expr* is the Python literal threaded as the discriminator scope:
+        ``"None"`` for a mount at the BASE path (every row of the shared table is a
+        legitimate source — rule a), or a quoted ``@discriminatorValue`` for a mount
+        under a subtype's segment (rule b).
+
+        *target_discs* is the relation NAME's decision set across EVERY mount of
+        that name in the hierarchy (:func:`_m2m_target_discs`) — the same decision
+        the Protocol seam signature derives from, so this call site and the seam
+        cannot disagree on the ``target_subtype`` parameter's arity.
+
+        *gated* — True for a subtype mount — composes the seam's OWN
+        ``find_by_id(subtype, id)`` (the exact lookup the per-subtype GET route
+        already calls, and the ``tph-cross-subtype-404`` conformance scenario
+        already gates) as a subtype-ownership check BEFORE the join: a miss
+        returns ``[]`` (HTTP 200), never 404 and never the ``find_related_*`` call.
+        This ENFORCES rule (c) in generated code rather than delegating it to the
+        consumer — a ``find_related_*`` implementation that forgets to filter by
+        subtype can no longer leak a sibling's rows, because it is never reached
+        for a mismatched id. No new query strategy: it reuses a method the
+        consumer must already implement correctly. False (the BASE mount) skips
+        the gate — a redundant lookup there would be pure overhead, since every
+        row of the shared table is already a legitimate source (rule a)."""
+        lines = [
+            f'@router.get("{route}")',
+            f"def {handler_name}(",
+            f"    {pk_param}: {pk_type},",
+            f"    repo: Annotated[{repo_class}, Depends(get_repository)],",
+            ") -> list[Any]:",
         ]
+        if gated:
+            lines += [
+                f"    if repo.find_by_id({subtype_expr}, {pk_param}) is None:",
+                "        return []",
+            ]
+        lines.append(
+            f"    return repo.find_related_{d.relation_name}"
+            f"({subtype_expr}, {pk_param}{_target_subtype_arg(d, target_discs)})"
+        )
+        return lines
 
     def _emit_tph_list_body(
         self, subtype_expr: str, fields_const: str, ops_const: str, repo_var: str = "repo"
@@ -528,14 +638,27 @@ class RouterGenerator:
             "    return rows",
         ]
 
-    def _render_tph_router(self, entity: MetaObject, plan: TphPlan) -> str:
+    def _render_tph_router(
+        self,
+        entity: MetaObject,
+        plan: TphPlan,
+        object_index: dict[str, MetaObject],
+        column_naming: str = DEFAULT_COLUMN_NAMING,
+    ) -> str:
         """FR-017 TPH: emit the discriminator base's router — a polymorphic collection
         at the base path + a full per-subtype CRUD set at /<base>/<segment>. The repo
         seam is subtype-keyed (the ``@discriminatorValue``, or ``None`` for the base);
-        the consumer's repo applies the single-table discriminator scope."""
+        the consumer's repo applies the single-table discriminator scope.
+
+        FW-8: also emits M:N traversal routes — one for every relationship the BASE
+        resolves (rule a), and one for every relationship each CONCRETE SUBTYPE
+        resolves, INHERITED ones included (rule b/d). ``resolve_m2m_descriptors`` is
+        called directly against the base and against each subtype's entity (never via
+        ``render_router``, which returns ``None`` for a TPH subtype before reaching
+        M:N resolution at all — the two independent gaps this fix closes)."""
         short_name = entity.name
         snake = _snake_case(short_name)
-        plural = _plural_lowercase(short_name)
+        plural = _route_path(short_name)
         pk_param = f"{snake}_id"
         # PK type from the BASE's declared primary key (subtypes share the
         # base's single table — mirrors the C# TPH pkType threading).
@@ -612,6 +735,39 @@ class RouterGenerator:
                 "        dto.pop(_frozen, None)",
             ]
 
+        # FW-8 — FR-018 x FR-017: M:N traversal inside a TPH hierarchy. Resolved
+        # directly against the base and against each subtype's OWN entity (never via
+        # `render_router`, which bails out for a TPH subtype before any M:N question
+        # at all). `resolve_m2m_descriptors` reads the RESOLVING `children()`
+        # (m2m_relationships), so a subtype's list already includes relationships
+        # inherited from the base or an abstract intermediate level — that overlap
+        # with the base's own list is rule (b), not a bug.
+        base_m2m = resolve_m2m_descriptors(entity, object_index, column_naming)
+        sub_m2m: dict[str, list[M2mDescriptor]] = {
+            st.entity.name: resolve_m2m_descriptors(st.entity, object_index, column_naming)
+            for st in plan.subtypes
+        }
+        # One `find_related_<relation>` Protocol seam per DISTINCT relation name
+        # anywhere in the hierarchy — mirrors the sort/required/frozen unions above.
+        # `subtype` threads through exactly like every other TPH seam method: `None`
+        # from the base route, the @discriminatorValue from a subtype route.
+        m2m_union: list[M2mDescriptor] = list(base_m2m)
+        m2m_seen = {d.relation_name for d in m2m_union}
+        for st in plan.subtypes:
+            for d in sub_m2m[st.entity.name]:
+                if d.relation_name not in m2m_seen:
+                    m2m_seen.add(d.relation_name)
+                    m2m_union.append(d)
+        # `target_subtype` presence is decided per relation NAME across EVERY mount
+        # of that name — base path and subtype segments together — never by the
+        # first descriptor the union kept: a subtype may SHADOW a base-declared
+        # relationship with a target of different TPH-ness, and the seam signature
+        # and every call site below derive from this one map.
+        m2m_target_discs = _m2m_target_discs(
+            list(base_m2m)
+            + [d for st in plan.subtypes for d in sub_m2m[st.entity.name]]
+        )
+
         h = generated_header(short_name, _effective_fqn(entity)).rstrip()
         parts: list[str] = []
         parts.append(
@@ -705,6 +861,15 @@ class RouterGenerator:
         parts.append("    def create(self, subtype: str, dto: Any) -> Any: ...")
         parts.append(f"    def update(self, subtype: str, id: {pk_type}, dto: Any) -> Any | None: ...")
         parts.append(f"    def delete(self, subtype: str, id: {pk_type}) -> bool: ...")
+        # FW-8: one find_related_<relation> seam per relation name resolved ANYWHERE
+        # in the hierarchy (base ∪ every subtype) — `subtype` scopes the traversal the
+        # same way every method above does; the consumer verifies a subtype-scoped id
+        # really is that subtype's, answering [] rather than a sibling's rows.
+        for d in m2m_union:
+            parts.append(
+                f"    def find_related_{d.relation_name}(self, subtype: str | None, id: {pk_type}"
+                f"{_target_subtype_param(m2m_target_discs[d.relation_name])}) -> list[Any]: ..."
+            )
         parts.append("")
         parts.append("")
         parts.append(f"def get_repository() -> {repo_class}:")
@@ -799,6 +964,27 @@ class RouterGenerator:
             parts.append("")
             parts.append("")
 
+            # FW-8 rule (b)/(d): every relationship THIS subtype resolves — inherited
+            # from the base or an abstract intermediate level included — mounted under
+            # its own segment. Stays inside the subtype loop (registered before the
+            # base's `/{id}` routes below) for the same reason the CRUD block above
+            # does: a literal segment must be tried before a dynamic one, or FastAPI's
+            # path-param coercion 422s before a later, more specific route is tried.
+            for d in sub_m2m[sub]:
+                parts.extend(self._emit_tph_m2m_route(
+                    d,
+                    handler_name=f"list_{plural}_{sfx}_{d.relation_name}",
+                    route=f"/{seg}/{{{pk_param}}}/{d.relation_name}",
+                    pk_param=pk_param,
+                    pk_type=pk_type,
+                    repo_class=repo_class,
+                    subtype_expr=f'"{val}"',
+                    gated=True,
+                    target_discs=m2m_target_discs[d.relation_name],
+                ))
+                parts.append("")
+                parts.append("")
+
         # --- Polymorphic base routes LAST (so /{id} doesn't shadow /<segment>). ---
         parts.extend(list_sig(f"list_{plural}", ""))
         parts.extend(self._emit_tph_list_body("None", fields_const, ops_const))
@@ -815,6 +1001,24 @@ class RouterGenerator:
         parts.append("    return row")
         parts.append("")
 
+        # FW-8 rule (a): every relationship the BASE resolves — every row of the
+        # shared table is a legitimate source, so this is the same shape a vanilla
+        # entity's mount gets (subtype=None, no discriminator gate).
+        for d in base_m2m:
+            parts.append("")
+            parts.extend(self._emit_tph_m2m_route(
+                d,
+                handler_name=f"list_{snake}_{d.relation_name}",
+                route=f"/{{{pk_param}}}/{d.relation_name}",
+                pk_param=pk_param,
+                pk_type=pk_type,
+                repo_class=repo_class,
+                subtype_expr="None",
+                gated=False,
+                target_discs=m2m_target_discs[d.relation_name],
+            ))
+            parts.append("")
+
         return "\n".join(parts)
 
     def render_router(
@@ -868,7 +1072,7 @@ class RouterGenerator:
         if object_index is not None:
             plan = tph_plan_for(entity, object_index)
             if plan is not None:
-                return self._render_tph_router(entity, plan)
+                return self._render_tph_router(entity, plan, object_index, column_naming)
 
         m2m: list[M2mDescriptor] = (
             resolve_m2m_descriptors(entity, object_index, column_naming)
@@ -878,7 +1082,7 @@ class RouterGenerator:
 
         short_name = entity.name
         snake = _snake_case(short_name)
-        plural = _plural_lowercase(short_name)
+        plural = _route_path(short_name)
         pk_param = f"{snake}_id"
         pk = _pk_py_type(entity)
         pk_type = pk.expr

{metaobjects-1.0.4 → metaobjects-1.0.5rc3}/src/metaobjects/library/embedded_library.py

@@ -11,7 +11,7 @@ EMBEDDED_LIBRARY: dict[str, str] = {
     'ai/model': '# library/ai/model.yaml — the CORE layer: the LLM-call trace envelope.\n#\n# Adopters opt in via `libraries: ["ai"]`, then `extends: "metaobjects::ai::LlmCallBase"`.\n#\n# This layer declares NO `source.rdb`, so opting into `"ai"` alone adds zero tables and\n# zero generated code — the design is present and resolvable, and nothing else happens\n# until the adopter adds `"ai/db"`. See library/iam/model.yaml for the full rationale.\n#\n# This file was split out of the former `library/ai/llm-call.yaml`, which shipped the\n# abstract base and a concrete `LlmCall` carrying `source.rdb` together. That was\n# recorded as an accepted wart on the grounds that splitting would change what existing\n# `ai` adopters get; a sweep of the estate found there are none, so it was closed rather\n# than documented (FR-043 Amendment 1).\nmetadata:\n  package: metaobjects::ai\n  children:\n    - object.entity:\n        name: LlmCallBase\n        abstract: true\n        children:\n          - field.uuid:     { name: traceId }\n          - field.uuid:     { name: spanId }\n          - field.uuid:     { name: parentSpanId }\n          - field.string:   { name: sessionId }\n          - field.string:   { name: callType }\n          - field.string:   { name: system }\n          - field.string:   { name: requestModel }\n          - field.string:   { name: responseModel }\n          - field.int:      { name: inputTokens }\n          - field.int:      { name: outputTokens }\n          - field.currency: { name: costMinor, currency: USD }\n          - field.int:      { name: latencyMs }\n          - field.string:   { name: finishReason }\n          - field.string:   { name: status }\n          - field.string:   { name: errorDetail }\n          - field.timestamp: { name: startedAt }\n          - field.string:   { name: llmRequest,  dbColumnType: jsonb }   # generic jsonb (no objectRef)\n          - field.string:   { name: llmResponse, dbColumnType: jsonb }\n    - object.entity:\n        name: LlmCall\n        extends: metaobjects::ai::LlmCallBase\n        description: The concrete trace row. Its `source.rdb` lives in db.yaml, so opting into the core layer alone declares the shape without proposing a table.\n        children:\n          - identity.primary: { name: id, fields: ["spanId"] }\n',
     'ai/requirements': "# library/ai/requirements.yaml — what the LLM-call trace envelope PROMISES.\n#\n# A RETROFIT, not new design: llm-call.yaml landed 2026-06-03 and `requirement.functional`\n# first appears 2026-08-11, so the library could not have carried requirements when it was\n# written. That is why this file is worth reading as a worked example — it shows what\n# declaring the design of something that already exists actually turns up.\n#\n# The entry that earns its keep is `typedIo`, honestly `partial` + `accepted`: the library\n# declares the ENVELOPE and the adopter declares the typed VO columns. Recording that seam\n# in the ledger is where an agent meets it, before adding a fourth trace column.\n#\n# HIERARCHY IS NESTING, and the L4/L5 split is grain. An L4 names the OBJECT it is about;\n# the fields that carry it hang off it as an L5 child. Writing the fields at L4 is\n# ERR_REQUIREMENT_L4_NOT_OBJECT, and writing the concerns as SIBLINGS of the L2 leaves the\n# L2 claiming nothing — both of which this file did until the standalone verify gate\n# existed (`cli/test/shipped-library-verify.test.ts`).\nmetadata:\n  package: metaobjects::ai\n  children:\n    - requirement.functional:\n        name: llmTracing\n        level: 2\n        status: live\n        statement: Every call to a language model leaves a row that says what was asked, what came back, what it cost and how long it took.\n        counterexample: A spend figure nobody can attribute to a call.\n        description: The segment this library covers. Its three children below are the concerns it decomposes into.\n        children:\n          - requirement.functional:\n              name: envelope\n              level: 4\n              status: live\n              statement: A trace row identifies its call and its place in a trace — trace, span, parent span, session, call type, system.\n              counterexample: A log line that cannot be joined to the request that produced it.\n              implementedBy: [LlmCallBase]\n              children:\n                - requirement.functional:\n                    name: traceAddressing\n                    level: 5\n                    status: live\n                    statement: The four addressing columns are declared on the base — trace, span, parent span and session.\n                    counterexample: A row whose place in a trace is inferred from insertion order.\n                    description: >-\n                      The member grain exists here so the claim RESOLVES against the fields\n                      themselves: renaming or dropping one of them dangles this reference and\n                      fails the build, which naming the object alone would not.\n                    implementedBy: [LlmCallBase.traceId, LlmCallBase.spanId, LlmCallBase.parentSpanId, LlmCallBase.sessionId]\n\n          - requirement.functional:\n              name: accounting\n              level: 4\n              status: live\n              statement: A trace row carries the tokens in, the tokens out, and the cost in integer minor units.\n              counterexample: A cost stored as a float.\n              description: >-\n                `field.currency` — integer minor units on the wire, always. Float arithmetic for\n                money is forbidden by the cross-port wire contract, and a spend total is exactly\n                the sum that exposes it.\n              implementedBy: [LlmCallBase]\n              children:\n                - requirement.functional:\n                    name: tokenAndCostColumns\n                    level: 5\n                    status: live\n                    statement: Tokens in, tokens out and cost are three declared columns, the cost a field.currency.\n                    counterexample: A cost column declared as a double.\n                    implementedBy: [LlmCallBase.inputTokens, LlmCallBase.outputTokens, LlmCallBase.costMinor]\n\n          - requirement.functional:\n              name: typedIo\n              level: 4\n              status: partial\n              disposition: accepted\n              statement: The request and response bodies are stored as structured jsonb, not as opaque text.\n              counterexample: A prompt stored as a string nobody can query a field out of.\n              notes: >-\n                The library declares the two columns as generic jsonb with no `@objectRef`,\n                because it cannot know the adopter's request/response shape. Typing them is the\n                ADOPTER's move: declare an `object.value` and overlay the field with\n                `@objectRef` + `@storage: jsonb`. This is the seam ADR-0024 drew, recorded here\n                rather than in prose so it is in the ledger an agent reads before adding a\n                fourth trace column of its own.\n              implementedBy: [LlmCallBase]\n              children:\n                - requirement.functional:\n                    name: jsonbBodies\n                    level: 5\n                    status: live\n                    statement: The request and response bodies are declared as jsonb columns on the base.\n                    counterexample: A prompt stored in a text column.\n                    description: >-\n                      `live` where its parent is `partial`, and the split is the point: the\n                      COLUMNS are shipped and this claim is fully realised; what is outstanding\n                      is the TYPING of them, which is the parent's gap and the adopter's move.\n                    implementedBy: [LlmCallBase.llmRequest, LlmCallBase.llmResponse]\n\n    - requirement.architectural:\n        name: traceRowsCarryTiming\n        status: live\n        statement: Every trace row records when the call started and how long it took.\n        counterexample: A latency figure derived from log timestamps after the fact.\n        description: >-\n          Architectural, so it propagates down `extends` to every adopter entity deriving\n          from LlmCallBase — which is the point: an adopter's own trace table is claimed\n          by this requirement for free, and dropping the columns breaks the build.\n        implementedBy: [LlmCallBase]\n\n    - requirement.architectural:\n        name: traceRowsCarryOutcome\n        status: live\n        statement: Every trace row records how the call ended — a status, a finish reason, and the error detail when there was one.\n        counterexample: A failed call indistinguishable from one that never happened.\n        implementedBy: [LlmCallBase]\n",
     'iam/db': '# library/iam/db.yaml — the DB PERSISTENCE layer for metaobjects::iam.\n#\n# Opted into as `"iam/db"`, which IMPLIES `"iam"`: this file is nothing but\n# `overlay: true` redeclarations, and an overlay whose target was never declared is\n# ERR_OVERLAY_NO_TARGET.\n#\n# It carries exactly two kinds of child — `source.rdb` and `index.lookup` — and nothing\n# else. The field set, the identities and the relationships all live in model.yaml,\n# because they are the DESIGN; what lives here is where the rows go and which lookups are\n# worth an index. Add a field here and the core layer stops being the whole model, which\n# is the thing the split exists to guarantee.\n#\n# Physical names are `iam_`-prefixed. Two reasons, both real: `user` and `group` are\n# reserved words in Postgres, and an adopter very likely has tables of their own by those\n# names. A library that collides on a table name is a library nobody can adopt.\nmetadata:\n  package: metaobjects::iam\n  children:\n    - object.entity:\n        name: User\n        overlay: true\n        children:\n          - source.rdb: { table: iam_user, role: primary }\n\n    - object.entity:\n        name: GroupType\n        overlay: true\n        children:\n          - source.rdb: { table: iam_group_type, role: primary }\n\n    - object.entity:\n        name: Group\n        overlay: true\n        children:\n          - source.rdb: { table: iam_group, role: primary }\n          # Nesting is walked parent-ward constantly; the FK alone gives no index.\n          - index.lookup: { name: ixParent, fields: [parentId] }\n\n    - object.entity:\n        name: Role\n        overlay: true\n        children:\n          - source.rdb: { table: iam_role, role: primary }\n\n    - object.entity:\n        name: Permission\n        overlay: true\n        children:\n          - source.rdb: { table: iam_permission, role: primary }\n\n    - object.entity:\n        name: GroupMember\n        overlay: true\n        children:\n          - source.rdb: { table: iam_group_member, role: primary }\n          # The composite PK covers (userId, groupId), so "who is in this group?" —\n          # the other direction — has no index without this one. Same reasoning for\n          # every ixSecond below.\n          - index.lookup: { name: ixGroup, fields: [groupId] }\n\n    - object.entity:\n        name: RolePermission\n        overlay: true\n        children:\n          - source.rdb: { table: iam_role_permission, role: primary }\n          - index.lookup: { name: ixPermission, fields: [permissionId] }\n\n    - object.entity:\n        name: UserRole\n        overlay: true\n        children:\n          - source.rdb: { table: iam_user_role, role: primary }\n          - index.lookup: { name: ixRole, fields: [roleId] }\n\n    - object.entity:\n        name: GroupMemberRole\n        overlay: true\n        children:\n          - source.rdb: { table: iam_group_member_role, role: primary }\n          # "who holds this role in this group?" — the scoped-grant read.\n          - index.lookup: { name: ixGroupRole, fields: [groupId, roleId] }\n',
-    'iam/model': '# library/iam/model.yaml — the CORE layer: identity and access management.\n#\n# Adopters opt in via `libraries: ["iam"]` in .metaobjects/config.json.\n#\n# This layer declares NO `source.rdb`, and that is the whole point of the split. A\n# sourceless object is inert by a contract that already ships: migrate skips an object\n# with no writable source, and codegen emits no route, queries, hooks, grid or form for\n# one (both citing #248 — persistability derives from source presence, never from the\n# object subtype). It still gets a type-only interface, so `extends` and reference work.\n#\n# So `libraries: ["iam"]` adds ZERO tables and ZERO generated code. What an adopter gains\n# is the design being present and resolvable: an agent working in the repo knows the\n# capability exists and can draw on it, and nothing else happens until the adopter adds\n# `"iam/db"`.\n#\n# Authoring discipline (FR-043 §3.1), so the departures are visible:\n#   - `field.uuid` + `generation: uuid` on principals; composite ASSIGNED keys on\n#     junctions. Never `increment` — a library cannot know the adopter\'s id strategy.\n#   - Physical names carry the `iam_` prefix (in db.yaml): `user` and `group` are\n#     reserved words in Postgres, and an adopter has tables of their own.\n#   - No adopter-facing profile data. That arrives by `overlay: true`.\n#   - No credentials. See requirements.yaml → `noCredentialsOnUser`.\nmetadata:\n  package: metaobjects::iam\n  children:\n    - object.entity:\n        name: IamBase\n        abstract: true\n        description: Shared shape of every iam principal and definition — a stable uuid plus change timestamps. Junctions do not extend it; they are addressed by their participants.\n        children:\n          - field.uuid:      { name: id, required: true }\n          - field.timestamp: { name: createdAt, autoSet: onCreate }\n          - field.timestamp: { name: updatedAt, autoSet: onUpdate }\n\n    - object.entity:\n        name: User\n        extends: IamBase\n        description: A person or service account that can be granted access. Carries no authentication secret of any kind — see the noCredentialsOnUser requirement.\n        children:\n          - field.string:    { name: username, required: true, maxLength: 64, filterable: true }\n          - field.string:    { name: email, required: true, maxLength: 254, stringFormat: email, filterable: true }\n          - field.string:    { name: displayName, maxLength: 120 }\n          # NOT `filterable: true`, deliberately. The loader warns when a filterable\n          # field is in no identity — filtering on it sequential-scans — and a library\n          # must not ship a warning to every adopter. `username` and `email` carry it\n          # because they have identity.secondary; `status` does not. An adopter who\n          # wants to filter on status overlays `filterable` AND an index together,\n          # which is exactly what the layer split is for.\n          - field.enum:      { name: status, required: true, values: [invited, active, suspended, closed], default: active }\n          - field.timestamp: { name: emailVerifiedAt }\n          - field.timestamp: { name: lastSeenAt }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqUsername, fields: [username] }\n          - identity.secondary: { name: uqEmail, fields: [email] }\n          - relationship.association: { name: groups, objectRef: Group, cardinality: many, through: GroupMember }\n          - relationship.association: { name: roles,  objectRef: Role,  cardinality: many, through: UserRole }\n\n    - object.entity:\n        name: GroupType\n        extends: IamBase\n        description: What KIND of group this is — a team, a tenant, a project. An entity rather than an enum, because "which roles may be held in this kind of group" is data an adopter extends, and an enum\'s values cannot be extended by overlay.\n        children:\n          - field.string: { name: key, required: true, maxLength: 64 }\n          - field.string: { name: name, required: true, maxLength: 120 }\n          - field.string: { name: description, maxLength: 500 }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqKey, fields: [key] }\n\n    - object.entity:\n        name: Group\n        extends: IamBase\n        description: A nestable collection of users, of a declared GroupType. Nesting is by parentId; acyclicity is an invariant the schema cannot express — see the acyclicGroupNesting requirement.\n        children:\n          - field.uuid:   { name: groupTypeId, required: true }\n          - field.uuid:   { name: parentId }\n          - field.string: { name: key, required: true, maxLength: 64 }\n          # Not filterable for the same reason as User.status above.\n          - field.string: { name: name, required: true, maxLength: 120 }\n          - field.string: { name: description, maxLength: 500 }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqKey, fields: [key] }\n          - identity.reference: { name: fkGroupType, fields: [groupTypeId], references: GroupType, onDelete: restrict }\n          - identity.reference: { name: fkParent,    fields: [parentId],    references: Group,     onDelete: restrict }\n\n    - object.entity:\n        name: Role\n        extends: IamBase\n        description: A reusable bundle of permissions. Code never compares a role NAME to a literal — it asks whether a user holds a permission, and the mapping is data.\n        children:\n          - field.string: { name: key, required: true, maxLength: 64 }\n          - field.string: { name: name, required: true, maxLength: 120 }\n          - field.string: { name: description, maxLength: 500 }\n          - field.uuid:   { name: groupTypeId, description: "When set, this role may be held only within groups of this type; absent means grantable anywhere." }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqKey, fields: [key] }\n          - identity.reference: { name: fkGroupType, fields: [groupTypeId], references: GroupType, onDelete: restrict }\n          - relationship.association: { name: permissions, objectRef: Permission, cardinality: many, through: RolePermission }\n\n    - object.entity:\n        name: Permission\n        extends: IamBase\n        description: "The assignable unit — a stable <resource>:<action> key the application checks against. An entity, not an enum, on ADR-0037\'s own reasoning: it has its own identity, its own lifecycle, and a junction with real foreign keys."\n        children:\n          - field.string: { name: key, required: true, maxLength: 128, description: "Stable <resource>:<action> key the application checks against." }\n          - field.string: { name: description, maxLength: 500 }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqKey, fields: [key] }\n\n    # ---- grant surface: every grant is a row, addressed by its participants ----\n    #\n    # Junctions do NOT extend IamBase: they have no identity of their own, and adding a\n    # surrogate uuid to a row whose identity IS its participants invites a duplicate.\n\n    - object.entity:\n        name: GroupMember\n        description: A user\'s membership of a group.\n        children:\n          - field.uuid:      { name: userId,  required: true }\n          - field.uuid:      { name: groupId, required: true }\n          - field.timestamp: { name: joinedAt, autoSet: onCreate }\n          - identity.primary:   { name: pk, fields: [userId, groupId], generation: assigned }\n          - identity.reference: { name: fkUser,  fields: [userId],  references: User,  onDelete: cascade }\n          - identity.reference: { name: fkGroup, fields: [groupId], references: Group, onDelete: cascade }\n\n    - object.entity:\n        name: RolePermission\n        description: A permission granted by a role.\n        children:\n          - field.uuid: { name: roleId,       required: true }\n          - field.uuid: { name: permissionId, required: true }\n          - identity.primary:   { name: pk, fields: [roleId, permissionId], generation: assigned }\n          - identity.reference: { name: fkRole,       fields: [roleId],       references: Role,       onDelete: cascade }\n          - identity.reference: { name: fkPermission, fields: [permissionId], references: Permission, onDelete: restrict }\n\n    - object.entity:\n        name: UserRole\n        description: A system-wide grant of a role to a user.\n        children:\n          - field.uuid:      { name: userId, required: true }\n          - field.uuid:      { name: roleId, required: true }\n          - field.timestamp: { name: grantedAt, autoSet: onCreate }\n          - identity.primary:   { name: pk, fields: [userId, roleId], generation: assigned }\n          - identity.reference: { name: fkUser, fields: [userId], references: User, onDelete: cascade }\n          - identity.reference: { name: fkRole, fields: [roleId], references: Role, onDelete: restrict }\n\n    - object.entity:\n        name: GroupMemberRole\n        description: A grant of a role to a user WITHIN one group. Three foreign keys, so it is not an M:N @through junction (which must declare exactly two identity.reference children); it is read by explicit finders.\n        children:\n          - field.uuid:      { name: userId,  required: true }\n          - field.uuid:      { name: groupId, required: true }\n          - field.uuid:      { name: roleId,  required: true }\n          - field.timestamp: { name: grantedAt, autoSet: onCreate }\n          - identity.primary:   { name: pk, fields: [userId, groupId, roleId], generation: assigned }\n          - identity.reference: { name: fkUser,  fields: [userId],  references: User,  onDelete: cascade }\n          - identity.reference: { name: fkGroup, fields: [groupId], references: Group, onDelete: cascade }\n          - identity.reference: { name: fkRole,  fields: [roleId],  references: Role,  onDelete: restrict }\n',
+    'iam/model': '# library/iam/model.yaml — the CORE layer: identity and access management.\n#\n# Adopters opt in via `libraries: ["iam"]` in .metaobjects/config.json.\n#\n# This layer declares NO `source.rdb`, and that is the whole point of the split. A\n# sourceless object is inert by a contract that already ships: migrate skips an object\n# with no writable source, and codegen emits no route, queries, hooks, grid or form for\n# one (both citing #248 — persistability derives from source presence, never from the\n# object subtype). It still gets a type-only interface, so `extends` and reference work.\n#\n# So `libraries: ["iam"]` adds ZERO tables and ZERO generated code. What an adopter gains\n# is the design being present and resolvable: an agent working in the repo knows the\n# capability exists and can draw on it, and nothing else happens until the adopter adds\n# `"iam/db"`.\n#\n# Authoring discipline (FR-043 §3.1), so the departures are visible:\n#   - `field.uuid` + `generation: uuid` on principals; composite ASSIGNED keys on\n#     junctions. Never `increment` — a library cannot know the adopter\'s id strategy.\n#   - Physical names carry the `iam_` prefix (in db.yaml): `user` and `group` are\n#     reserved words in Postgres, and an adopter has tables of their own.\n#   - No adopter-facing profile data. That arrives by `overlay: true`.\n#   - No credentials. See requirements.yaml → `noCredentialsOnUser`.\nmetadata:\n  package: metaobjects::iam\n  children:\n    - object.entity:\n        name: IamBase\n        abstract: true\n        description: Shared shape of every iam principal and definition — a stable uuid plus change timestamps. Junctions do not extend it; they are addressed by their participants.\n        children:\n          - field.uuid:      { name: id, required: true }\n          - field.timestamp: { name: createdAt, autoSet: onCreate }\n          - field.timestamp: { name: updatedAt, autoSet: onUpdate }\n\n    - object.entity:\n        name: User\n        extends: IamBase\n        description: A person or service account that can be granted access. Carries no authentication secret of any kind — see the noCredentialsOnUser requirement.\n        children:\n          - field.string:    { name: username, required: true, maxLength: 64, filterable: true }\n          - field.string:    { name: email, required: true, maxLength: 254, stringFormat: email, filterable: true }\n          - field.string:    { name: displayName, maxLength: 120 }\n          # NOT `filterable: true`, deliberately. The loader warns when a filterable\n          # field is in no identity — filtering on it sequential-scans — and a library\n          # must not ship a warning to every adopter. `username` and `email` carry it\n          # because they have identity.secondary; `status` does not. An adopter who\n          # wants to filter on status overlays `filterable` AND an index together,\n          # which is exactly what the layer split is for.\n          - field.enum:      { name: status, required: true, values: [invited, active, suspended, closed], default: active }\n          - field.timestamp: { name: emailVerifiedAt }\n          - field.timestamp: { name: lastSeenAt }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqUsername, fields: [username] }\n          - identity.secondary: { name: uqEmail, fields: [email] }\n          - relationship.association: { name: groups, objectRef: Group, cardinality: many, through: GroupMember }\n          - relationship.association: { name: roles,  objectRef: Role,  cardinality: many, through: UserRole }\n\n    - object.entity:\n        name: GroupType\n        extends: IamBase\n        description: What KIND of group this is — a team, a tenant, a project. An entity rather than an enum, because "which roles may be held in this kind of group" is data an adopter extends, and an enum\'s values cannot be extended by overlay.\n        children:\n          - field.string: { name: key, required: true, maxLength: 64 }\n          - field.string: { name: name, required: true, maxLength: 120 }\n          - field.string: { name: description, maxLength: 500 }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqGroupTypeKey, fields: [key] }\n\n    - object.entity:\n        name: Group\n        extends: IamBase\n        description: A nestable collection of users, of a declared GroupType. Nesting is by parentId; acyclicity is an invariant the schema cannot express — see the acyclicGroupNesting requirement.\n        children:\n          - field.uuid:   { name: groupTypeId, required: true }\n          - field.uuid:   { name: parentId }\n          - field.string: { name: key, required: true, maxLength: 64 }\n          # Not filterable for the same reason as User.status above.\n          - field.string: { name: name, required: true, maxLength: 120 }\n          - field.string: { name: description, maxLength: 500 }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqGroupKey, fields: [key] }\n          - identity.reference: { name: fkGroupType, fields: [groupTypeId], references: GroupType, onDelete: restrict }\n          - identity.reference: { name: fkParent,    fields: [parentId],    references: Group,     onDelete: restrict }\n\n    - object.entity:\n        name: Role\n        extends: IamBase\n        description: A reusable bundle of permissions. Code never compares a role NAME to a literal — it asks whether a user holds a permission, and the mapping is data.\n        children:\n          - field.string: { name: key, required: true, maxLength: 64 }\n          - field.string: { name: name, required: true, maxLength: 120 }\n          - field.string: { name: description, maxLength: 500 }\n          - field.uuid:   { name: groupTypeId, description: "When set, this role may be held only within groups of this type; absent means grantable anywhere." }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqRoleKey, fields: [key] }\n          - identity.reference: { name: fkGroupType, fields: [groupTypeId], references: GroupType, onDelete: restrict }\n          - relationship.association: { name: permissions, objectRef: Permission, cardinality: many, through: RolePermission }\n\n    - object.entity:\n        name: Permission\n        extends: IamBase\n        description: "The assignable unit — a stable <resource>:<action> key the application checks against. An entity, not an enum, on ADR-0037\'s own reasoning: it has its own identity, its own lifecycle, and a junction with real foreign keys."\n        children:\n          - field.string: { name: key, required: true, maxLength: 128, description: "Stable <resource>:<action> key the application checks against." }\n          - field.string: { name: description, maxLength: 500 }\n          - identity.primary:   { name: pk, fields: [id], generation: uuid }\n          - identity.secondary: { name: uqPermissionKey, fields: [key] }\n\n    # ---- grant surface: every grant is a row, addressed by its participants ----\n    #\n    # Junctions do NOT extend IamBase: they have no identity of their own, and adding a\n    # surrogate uuid to a row whose identity IS its participants invites a duplicate.\n\n    - object.entity:\n        name: GroupMember\n        description: A user\'s membership of a group.\n        children:\n          - field.uuid:      { name: userId,  required: true }\n          - field.uuid:      { name: groupId, required: true }\n          - field.timestamp: { name: joinedAt, autoSet: onCreate }\n          - identity.primary:   { name: pk, fields: [userId, groupId], generation: assigned }\n          - identity.reference: { name: fkUser,  fields: [userId],  references: User,  onDelete: cascade }\n          - identity.reference: { name: fkGroup, fields: [groupId], references: Group, onDelete: cascade }\n\n    - object.entity:\n        name: RolePermission\n        description: A permission granted by a role.\n        children:\n          - field.uuid: { name: roleId,       required: true }\n          - field.uuid: { name: permissionId, required: true }\n          - identity.primary:   { name: pk, fields: [roleId, permissionId], generation: assigned }\n          - identity.reference: { name: fkRole,       fields: [roleId],       references: Role,       onDelete: cascade }\n          - identity.reference: { name: fkPermission, fields: [permissionId], references: Permission, onDelete: restrict }\n\n    - object.entity:\n        name: UserRole\n        description: A system-wide grant of a role to a user.\n        children:\n          - field.uuid:      { name: userId, required: true }\n          - field.uuid:      { name: roleId, required: true }\n          - field.timestamp: { name: grantedAt, autoSet: onCreate }\n          - identity.primary:   { name: pk, fields: [userId, roleId], generation: assigned }\n          - identity.reference: { name: fkUser, fields: [userId], references: User, onDelete: cascade }\n          - identity.reference: { name: fkRole, fields: [roleId], references: Role, onDelete: restrict }\n\n    - object.entity:\n        name: GroupMemberRole\n        description: A grant of a role to a user WITHIN one group. Three foreign keys, so it is not an M:N @through junction (which must declare exactly two identity.reference children); it is read by explicit finders.\n        children:\n          - field.uuid:      { name: userId,  required: true }\n          - field.uuid:      { name: groupId, required: true }\n          - field.uuid:      { name: roleId,  required: true }\n          - field.timestamp: { name: grantedAt, autoSet: onCreate }\n          - identity.primary:   { name: pk, fields: [userId, groupId, roleId], generation: assigned }\n          - identity.reference: { name: fkUser,  fields: [userId],  references: User,  onDelete: cascade }\n          - identity.reference: { name: fkGroup, fields: [groupId], references: Group, onDelete: cascade }\n          - identity.reference: { name: fkRole,  fields: [roleId],  references: Role,  onDelete: restrict }\n',
     'iam/requirements': '# library/iam/requirements.yaml — what this library\'s design PROMISES.\n#\n# This is what makes iam a library rather than a schema snippet. Without requirements an\n# adopter gets nine tables; with them they get nine tables plus a build that is held to\n# "no authorization decision is hard-wired to a name", which no snippet can do.\n#\n# Two reading rules, both load-bearing:\n#\n#   `live` here means "the model AS SHIPPED realises this" — never "your application\n#   does". A ledger binds to model nodes; runtime guarantees are the runtime\'s tests, and\n#   this library does not invent a way to point a requirement at code (@verifiedBy was\n#   retired for exactly that). Behaviour the model cannot carry ships as `partial` +\n#   `disposition: accepted` with a notes sentence naming what the adopter must do.\n#\n#   The functional tree roots at L2, not L1. L1 is the adopter\'s SOLUTION, and a library\n#   is by definition a segment of someone else\'s. Architectural claims ship flat.\n#\n# HIERARCHY IS NESTING, and the L4/L5 split is grain. The concerns are CHILDREN of the L2\n# rather than its siblings, and an L4 names the OBJECT it is about while the field that\n# carries it hangs off it as an L5 child. Written flat, the L2 claims nothing in its whole\n# subtree; written at L4, a field reference is ERR_REQUIREMENT_L4_NOT_OBJECT. Both shipped\n# here until the standalone verify gate existed (`cli/test/shipped-library-verify.test.ts`).\nmetadata:\n  package: metaobjects::iam\n  children:\n    # ---- functional: the L2 segment and the concerns nested under it --------\n    - requirement.functional:\n        name: accessControl\n        level: 2\n        status: live\n        statement: Who may do what is answered from stored grants, never from a name compared to a literal in code.\n        counterexample: A branch that reads `if (user.role === "admin")`.\n        description: The segment this library covers. The concerns beneath it are what it decomposes into.\n        children:\n          - requirement.functional:\n              name: identity\n              level: 4\n              status: live\n              statement: A person or service account is represented once, addressed by a uuid, and reachable by username or email.\n              counterexample: Two rows for the same person because the email changed.\n              implementedBy: [User]\n\n          - requirement.functional:\n              name: grouping\n              level: 4\n              status: live\n              statement: Users are collected into typed, nestable groups, and the kind of group is data rather than a hard-coded set.\n              counterexample: A `teamOrTenant` boolean.\n              implementedBy: [Group, GroupType, GroupMember]\n\n          - requirement.functional:\n              name: acyclicGroupNesting\n              level: 4\n              status: partial\n              disposition: accepted\n              statement: A group is never its own ancestor.\n              counterexample: Two groups each naming the other as parent.\n              notes: >-\n                The schema cannot express this — a self-referencing FK admits a cycle, and the\n                only relational forms that would catch it (a recursive CHECK, a closure table\n                maintained by trigger) are DB-specific and would not survive three dialects.\n                The adopter enforces it where the write happens. Recorded rather than omitted\n                so an agent reading the ledger before adding a parent-setting endpoint sees the\n                obligation.\n              implementedBy: [Group]\n\n          - requirement.functional:\n              name: grants\n              level: 4\n              status: live\n              statement: A role is granted to a user either system-wide or scoped to one group, and both are ordinary rows.\n              counterexample: A nullable `groupId` on one grant table, where NULL means "everywhere".\n              description: >-\n                Two junctions, not one with a nullable scope. A NULL in a unique key is DISTINCT\n                from every other NULL in SQL, so a nullable-scope design lets the same global\n                grant be inserted twice; the fix needs a partial index whose expression carries\n                a physical column name. Two composite-keyed tables need no escape hatch and\n                survive three dialects and five ports unchanged.\n              implementedBy: [UserRole, GroupMemberRole]\n\n          - requirement.functional:\n              name: roleScopedToGroupType\n              level: 4\n              status: partial\n              disposition: accepted\n              statement: A role bound to a group type is granted only within groups of that type.\n              counterexample: A "tenant admin" role granted inside a project group.\n              notes: >-\n                Expressing this relationally needs the grant row to carry the group\'s type and\n                a composite FK back to (group, type) — three foreign keys deep, unverified\n                across five ports\' DDL and ORM paths. The adopter checks it at the point of\n                grant. The declared half is the L5 child below; the enforcement is not.\n              implementedBy: [Role, GroupMemberRole]\n              children:\n                - requirement.functional:\n                    name: roleDeclaresItsGroupType\n                    level: 5\n                    status: live\n                    statement: A role declares the group type it is bound to, as a nullable reference.\n                    counterexample: A role whose intended scope is recoverable only from its name.\n                    description: >-\n                      `live` where its parent is `partial`, and the split is grain as much as\n                      verdict: the DECLARATION is shipped and resolves against the field itself,\n                      so dropping the column fails the build — while the ENFORCEMENT, which no\n                      schema here can carry, stays the parent\'s accepted gap.\n                    implementedBy: [Role.groupTypeId]\n\n          - requirement.functional:\n              name: decision\n              level: 4\n              status: live\n              statement: An authorization decision is the question "does this user hold this permission key", answered from rows.\n              counterexample: A hard-coded list of usernames that bypass a check.\n              implementedBy: [Permission, RolePermission]\n\n    # ---- architectural: prohibitions in force --------------------------------\n\n    - requirement.architectural:\n        name: grantsAreRows\n        status: live\n        statement: A grant exists only as a stored row; nothing is granted by naming, position or convention.\n        counterexample: A superuser recognised by username.\n        implementedBy: [UserRole, GroupMemberRole, RolePermission, GroupMember]\n\n    - requirement.architectural:\n        name: noCredentialsOnUser\n        status: live\n        statement: A user row carries no authentication secret — no password, no hash, no knowledge-based question or answer.\n        counterexample: A password or secret-answer column on the user table.\n        description: >-\n          Authentication is a separate capability with an entity per factor; this library\n          is identity and authorization only.\n        notes: >-\n          This is the one thing every reader of a user table proposes adding, and a real\n          legacy model of this shape stored a length-bounded plaintext password and a\n          knowledge-based secret pair on the user row. Stating it as a prohibition IN\n          FORCE — claimable, and rendered on agent/requirements.md — is what stops an\n          agent extending "the user model" from re-deriving it on sight. It is\n          `architectural`, not `retired`: retired is chartered for a capability built\n          here and removed, and this library never built one.\n        implementedBy: [User]\n\n    - requirement.architectural:\n        name: principalDeletionRevokesGrants\n        status: live\n        statement: Deleting a user or group removes its grants; deleting a role or permission still in use is refused.\n        counterexample: A grant row pointing at a user who no longer exists.\n        description: The referential rule in one sentence — cascade from a principal, restrict from a definition.\n        implementedBy: [GroupMember, UserRole, GroupMemberRole, RolePermission]\n\n    - requirement.architectural:\n        name: stableIdentifiers\n        status: live\n        statement: Every principal and definition is addressed by a uuid that never changes; every grant by its participants.\n        counterexample: A group referenced by its display name.\n        implementedBy: [IamBase]\n',
 }
 

{metaobjects-1.0.4 → metaobjects-1.0.5rc3}/src/metaobjects/meta/core/requirement/requirement_constants.py

@@ -9,8 +9,10 @@ the loader like everything else — never hand-parsed from a side file.
 # ---------------------------------------------------------------------------
 # Subtypes — the axis is the CHECK POLARITY, a genuine behaviour difference and
 # therefore a subtype under ADR-0037 §2:
-#   functional    -> EXISTENCE:    fails when nothing implements it
-#   architectural -> UNIVERSALITY: fails when something violates it
+#   functional    -> EXISTENCE:    `meta verify` warns when nothing implements it,
+#                                    and fails when a node it names is gone
+#   architectural -> UNIVERSALITY: `meta verify` fails a live policy applied to nothing
+#                                    (it does not check that each claimed node complies)
 # ---------------------------------------------------------------------------
 REQUIREMENT_SUBTYPE_FUNCTIONAL = "functional"
 REQUIREMENT_SUBTYPE_ARCHITECTURAL = "architectural"