metaobjects 0.24.0__tar.gz → 0.24.1__tar.gz

{metaobjects-0.24.0 → metaobjects-0.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: metaobjects
-Version: 0.24.0
+Version: 0.24.1
 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-0.24.0 → metaobjects-0.24.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "metaobjects"
-version = "0.24.0"
+version = "0.24.1"
 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-0.24.0 → metaobjects-0.24.1}/src/metaobjects/core_types.py

@@ -541,7 +541,13 @@ core_provider.add(
         sub_type=IDENTITY_SUBTYPE_SECONDARY,
         factory=MetaIdentity,
         attrs=[
-            AttrSchema(name=IDENTITY_ATTR_FIELDS, value_type=ATTR_SUBTYPE_STRING, required=True, is_array=True),
+            # #342: OPTIONAL, unlike identity.primary/reference. The real rule is
+            # @fields XOR @expr — a unique index may key off a raw expression
+            # instead of columns — and an exclusive-or is not expressible as a
+            # per-attr required flag, so it is enforced by the index-key
+            # validation pass (ERR_INVALID_INDEX). Required=True here fired first
+            # and made an expression index undeclarable.
+            AttrSchema(name=IDENTITY_ATTR_FIELDS, value_type=ATTR_SUBTYPE_STRING, required=False, is_array=True),
         ],
         child_rules=[ChildRule(TYPE_ATTR, "*")],
     )
@@ -576,7 +582,9 @@ for _idx_sub in INDEX_SUBTYPES:
             sub_type=_idx_sub,
             factory=MetaIndex,
             attrs=[
-                AttrSchema(name=INDEX_ATTR_FIELDS, value_type=ATTR_SUBTYPE_STRING, required=True, is_array=True),
+                # #342: OPTIONAL — the key is @fields XOR @expr, enforced by the
+                # index-key validation pass (ERR_INVALID_INDEX), not by this flag.
+                AttrSchema(name=INDEX_ATTR_FIELDS, value_type=ATTR_SUBTYPE_STRING, required=False, is_array=True),
             ],
             child_rules=[ChildRule(TYPE_ATTR, "*")],
         )

{metaobjects-0.24.0 → metaobjects-0.24.1}/src/metaobjects/errors.py

@@ -156,6 +156,23 @@ class ErrorCode(str, Enum):
     # SP-H Unit9 — @filterable: true on a field subtype with no filter-operator
     # band (e.g. field.object). Would silently generate an empty-ops filter.
     ERR_FILTERABLE_UNSUPPORTED_SUBTYPE = "ERR_FILTERABLE_UNSUPPORTED_SUBTYPE"
+    # #335 Half B — @sortable: true on an array field or a subtype with no
+    # filter-operator band (e.g. field.object). Would silently emit a sort
+    # entry over a column no dialect can ORDER BY.
+    ERR_SORTABLE_UNSUPPORTED_SUBTYPE = "ERR_SORTABLE_UNSUPPORTED_SUBTYPE"
+    # #335 Half A — a whole-object @agg:collect (no @of; the carrying field.object
+    # rolls related rows up as its declared @objectRef value object) is malformed:
+    # carrier is not a field.object with @objectRef, @via absent, @distinct declared
+    # (refused — a no-op whenever the value object carries the primary key), an
+    # @orderBy key not on the @via TERMINAL entity, or a member's declared type
+    # disagreeing with the matched terminal field's. Distinct from ERR_INVALID_ORIGIN
+    # so a fixture can tell this arm from a loader that still requires @of.
+    ERR_COLLECT_WHOLE_OBJECT = "ERR_COLLECT_WHOLE_OBJECT"
+    # #335 Half A — a whole-object @agg:collect's value-object member has no
+    # matching field (by name) on the @via terminal entity. The lowering
+    # projects exactly the declared members; failing open here is how #270
+    # turned a curated value object into the full entity.
+    ERR_COLLECT_MEMBER_UNRESOLVED = "ERR_COLLECT_MEMBER_UNRESOLVED"
     # ADR-0023 — a registration was attempted against a registry sealed after its
     # agreed metamodel-provider bootstrap. Codegen cannot invent metamodel attrs.
     ERR_REGISTRY_SEALED = "ERR_REGISTRY_SEALED"

{metaobjects-0.24.0 → metaobjects-0.24.1}/src/metaobjects/loader/validation_passes.py

@@ -26,6 +26,7 @@ from ..meta.core.field.field_constants import (
     FIELD_ATTR_INT_VALUE_MAP,
     FIELD_ATTR_OBJECT_REF,
     FIELD_ATTR_REQUIRED,
+    FIELD_ATTR_SORTABLE,
     FIELD_ATTR_STORAGE,
     FIELD_ATTR_VALUE_TYPE,
     FIELD_ATTR_VALUES,
@@ -124,8 +125,14 @@ from ..meta.core.object.object_constants import (
     OBJECT_SUBTYPE_PROJECTION,
     OBJECT_SUBTYPE_VALUE,
 )
-from ..meta.core.identity.identity_constants import IDENTITY_ATTR_FIELDS
+from ..meta.core.identity.identity_constants import (
+    IDENTITY_ATTR_FIELDS,
+    IDENTITY_SUBTYPE_SECONDARY,
+)
 from ..meta.core.index.index_constants import INDEX_ATTR_FIELDS, INDEX_SUBTYPE_LOOKUP
+from ..meta.persistence.db.db_constants import (
+    IDENTITY_SECONDARY_ATTR_EXPR as IDENTITY_ATTR_EXPR,
+)
 from ..source import resolved_source
 from ..naming_refs import did_you_mean_hint, resolve_object_ref
 
@@ -224,8 +231,10 @@ def run_validations(
     _validate_identity_passthrough(root, errors)
     _validate_max_occurs(root, registry, errors)
     _validate_filterable_has_index(root, warnings)
-    # SP-H Unit9 — @filterable on a subtype with no operator band → error.
+    # SP-H Unit9 — @filterable on a subtype with no operator band, or an array → error.
     _validate_filterable_has_supported_ops(root, errors)
+    # #335 Half B — @sortable on an array field, or a subtype with no operator band → error.
+    _validate_sortable_has_supported_subtype(root, errors)
     _validate_index_lookup_fields(root, errors)
 
 
@@ -1575,6 +1584,16 @@ def _validate_entity_field_ref(
     return (entity, field_node)
 
 
+class WalkedViaPath(NamedTuple):
+    """A fully-walked ``@via`` path: the relationship hop nodes in path order,
+    plus the entity they terminate at. Returned as a pair (rather than re-walking
+    for the terminal) because a second walk means a second copy of the ADR-0042
+    package-resolution rule — mirrors the TS ``WalkedViaPath``."""
+
+    hops: list[MetaData]
+    terminal: MetaData
+
+
 def _validate_via_path(
     via: str,
     context: str,
@@ -1583,12 +1602,15 @@ def _validate_via_path(
     errors: list[MetaError],
     origin_node: MetaData,
     referrer: str,
-) -> list[MetaData] | None:
+) -> WalkedViaPath | None:
     """Validate a dotted relationship path 'Entity.rel1[.rel2...]'.
 
-    Returns the walked relationship hop nodes (in path order) on full success
-    (FR-024 B5 runs the cardinality checks over them); appends ERR_INVALID_ORIGIN
-    and returns None if not.
+    Returns the walked relationship hop nodes (in path order) together with the
+    TERMINAL entity node on full success (FR-024 B5 runs the cardinality checks
+    over the hops; #335's whole-object @agg:collect has no @of entity, so its
+    @orderBy keys and value-object members resolve against the terminal);
+    appends ERR_INVALID_ORIGIN and returns None if not. ``terminal`` is defined
+    exactly when ``hops`` is — every early exit returns None.
 
     *origin_node* carries the parse-time envelope (files/json_path); *referrer*
     is the canonical referrer FQN (``<projection-FQN>::<fieldName>``) attached
@@ -1686,7 +1708,8 @@ def _validate_via_path(
         hops.append(rel_node)
         current_entity = next_entity
 
-    return hops
+    # current_entity is the terminal: every earlier exit returned None.
+    return WalkedViaPath(hops, current_entity)
 
 
 # ---------------------------------------------------------------------------
@@ -1995,6 +2018,61 @@ def _check_passthrough_type(
     )
 
 
+def _type_label(field: MetaData) -> str:
+    """A field's declared type on BOTH axes — ``field.<subType>`` plus ``[]`` when it is
+    an array. ADR-0039: resolved_is_array(), so array-ness inherited via extends counts.
+    Mirrors the TS ``_typeLabel``."""
+    return f"field.{field.sub_type}{'[]' if field.resolved_is_array() else ''}"
+
+
+def _check_collect_members(
+    ref_target: MetaData,
+    terminal: MetaData,
+    obj: MetaData,
+    field: MetaData,
+    src: object,
+    errors: list[MetaError],
+) -> None:
+    """#335 — a whole-object @agg:collect projects EXACTLY the declared value object's
+    members, matched BY NAME against the @via terminal entity's fields:
+
+     - an unmatched member is an error, never a silent drop. Failing open here is how
+       #270 turned a curated value object into the full entity, invisible in a diff
+       because the metadata still read as curated.
+     - a matched member must agree on BOTH type axes (#185 type-preserving doctrine),
+       so a scalar member cannot bind an array field or vice versa.
+
+    Both refusals carry a whole-object-specific code — ERR_COLLECT_MEMBER_UNRESOLVED for
+    the unmatched member, ERR_COLLECT_WHOLE_OBJECT for the type disagreement. The latter
+    is deliberately NOT the scalar arm's ERR_INVALID_ORIGIN: a loader that still requires
+    @of rejects this metadata with ERR_INVALID_ORIGIN too, so sharing the code would make
+    a corpus fixture pass on a port that implements nothing.
+
+    Mirrors the TS ``_checkCollectMembers``."""
+    # ADR-0039: resolving — a value object may inherit members via extends, and the
+    # terminal entity may inherit fields; own-only would silently skip inherited
+    # members, which is exactly the #270 bug class this guards.
+    terminal_fields = [c for c in terminal.children() if c.type == TYPE_FIELD]
+    for member in (c for c in ref_target.children() if c.type == TYPE_FIELD):
+        match = next((f for f in terminal_fields if f.name == member.name), None)
+        if match is None:
+            errors.append(MetaError(
+                f"origin.aggregate @agg:collect on {obj.name}.{field.name}: value-object "
+                f"member '{member.name}' has no matching field on '{terminal.name}' — a "
+                f"whole-object rollup projects exactly the declared members.",
+                ErrorCode.ERR_COLLECT_MEMBER_UNRESOLVED, envelope=src))
+            continue
+        member_label = _type_label(member)
+        match_label = _type_label(match)
+        if member_label != match_label:
+            errors.append(MetaError(
+                f"origin.aggregate @agg:collect on {obj.name}.{field.name}: value-object "
+                f"member '{member.name}' is {member_label} but "
+                f"'{terminal.name}.{match.name}' is {match_label} — a whole-object rollup "
+                f"preserves each member's type.",
+                ErrorCode.ERR_COLLECT_WHOLE_OBJECT, envelope=src))
+
+
 def _validate_order_by_keys(
     order_by: object,
     related_entity: MetaData | None,
@@ -2003,12 +2081,17 @@ def _validate_order_by_keys(
     label: str,
     origin_source: object,
     errors: list[MetaError],
+    code: ErrorCode = ErrorCode.ERR_INVALID_ORIGIN,
 ) -> None:
     """#195 — validate that ``@orderBy`` keys ('field[:asc|desc]') resolve against the
     RELATED entity's effective fields (the entity reached via @via/@of), and that any
     direction suffix is asc/desc. Shared by @agg:collect (element order) and origin.first
     (row selection). A missing related entity means a prior error already fired — skip.
-    Mirrors the TS _validateOrderByKeys."""
+    Mirrors the TS _validateOrderByKeys.
+
+    *code* lets #335's whole-object @agg:collect arm report ERR_COLLECT_WHOLE_OBJECT
+    instead; it defaults to ERR_INVALID_ORIGIN so the scalar @of and origin.first call
+    sites keep their existing envelope byte-for-byte."""
     if not isinstance(order_by, (list, tuple)) or related_entity is None:
         return
     for raw in order_by:
@@ -2027,7 +2110,7 @@ def _validate_order_by_keys(
                 MetaError(
                     f'{label} on {obj.name}.{field_name}: @orderBy key "{raw}" — no such '
                     f'field "{key}" on {related_entity.name}.',
-                    ErrorCode.ERR_INVALID_ORIGIN,
+                    code,
                     envelope=origin_source,
                 )
             )
@@ -2036,7 +2119,7 @@ def _validate_order_by_keys(
                 MetaError(
                     f'{label} on {obj.name}.{field_name}: @orderBy key "{raw}" — direction '
                     f"must be one of {'|'.join(SORT_ORDER_VALUES)}.",
-                    ErrorCode.ERR_INVALID_ORIGIN,
+                    code,
                     envelope=origin_source,
                 )
             )
@@ -2130,7 +2213,8 @@ def _validate_origin_paths(
                     )
                 via = origin.attr(ORIGIN_ATTR_VIA)
                 if isinstance(via, str) and via:
-                    hops = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                    walked = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                    hops = walked.hops if walked is not None else None
                     if hops is not None:
                         _check_passthrough_cardinality(hops, node.name, origin.source, errors)
                 elif from_target is not None and not is_value_host:
@@ -2226,20 +2310,94 @@ def _validate_origin_paths(
                             f"explicit @via (a quantifier has no @of to infer the path from).",
                             ErrorCode.ERR_INVALID_ORIGIN, envelope=src))
                     else:
-                        hops = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                        walked = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                        hops = walked.hops if walked is not None else None
                         if hops is not None:
                             _check_aggregate_cardinality(hops, node.name, src, errors)
                     continue
 
-                # --- count/sum/avg/min/max/collect: @of REQUIRED ---
+                # --- @of: REQUIRED for count/sum/avg/min/max; OPTIONAL for collect ---
+                # #335 — an @of-absent collect is a WHOLE-OBJECT rollup: collect the
+                # related rows as an array of the field's declared @objectRef value
+                # object rather than an array of one scalar column.
                 if not of_present:
-                    errors.append(
-                        MetaError(
-                            f"{ctx} is missing required attribute '@{ORIGIN_ATTR_OF}'",
-                            ErrorCode.ERR_INVALID_ORIGIN,
-                            envelope=src,
+                    if not is_collect:
+                        errors.append(
+                            MetaError(
+                                f"{ctx} is missing required attribute '@{ORIGIN_ATTR_OF}'",
+                                ErrorCode.ERR_INVALID_ORIGIN,
+                                envelope=src,
+                            )
                         )
-                    )
+                        continue
+                    # Whole-object rollup. The carrying field must be a field.object
+                    # naming a value object, and @via must be explicit (there is no @of
+                    # entity to infer the single-hop relation from).
+                    # ADR-0039: resolving — @objectRef may be inherited via extends.
+                    object_ref = node.get_meta_attr(FIELD_ATTR_OBJECT_REF)
+                    if node.sub_type != FIELD_SUBTYPE_OBJECT or not isinstance(object_ref, str) \
+                            or not object_ref:
+                        errors.append(MetaError(
+                            f"origin.aggregate @agg:collect on {obj.name}.{node.name}: @of is "
+                            f"omitted, so this is a whole-object rollup — the carrying field "
+                            f"must be a field.object declaring @objectRef (add @of to collect a "
+                            f"single column instead).",
+                            ErrorCode.ERR_COLLECT_WHOLE_OBJECT, envelope=src))
+                        continue
+                    # #210's value-only rule is PAYLOAD-scoped and never reaches a
+                    # projection-hosted field, so this branch enforces it itself.
+                    # Without it an @objectRef to an entity silently rolls up the FULL
+                    # entity — the #270 shape, this time baked into DDL.
+                    # ADR-0042 — a bare @objectRef resolves in the DECLARING owner's
+                    # package (an inherited field resolves in the package that declared it).
+                    ref_owner = node.parent or obj
+                    ref_pkg = ref_owner.package or ref_owner.file_default_package or ""
+                    ref_target = resolve_object_ref(root, object_ref, ref_pkg)
+                    if ref_target is not None and ref_target.sub_type != OBJECT_SUBTYPE_VALUE:
+                        errors.append(MetaError(
+                            f"origin.aggregate @agg:collect on {obj.name}.{node.name}: "
+                            f"@objectRef '{object_ref}' resolves to "
+                            f"{TYPE_OBJECT}.{ref_target.sub_type} — a whole-object rollup must "
+                            f"target an object.value (#210, ADR-0028).",
+                            ErrorCode.ERR_SUBTYPE_RULE_VIOLATION, envelope=src))
+                        continue
+                    # ADR-0039: own — origin.* never inherits (ADR-0029).
+                    via_attr = origin.attr(ORIGIN_ATTR_VIA)
+                    if not isinstance(via_attr, str) or not via_attr:
+                        errors.append(MetaError(
+                            f"origin.aggregate @agg:collect on {obj.name}.{node.name}: @via is "
+                            f"required on a whole-object rollup — there is no @of entity to "
+                            f"infer the relationship from.",
+                            ErrorCode.ERR_COLLECT_WHOLE_OBJECT, envelope=src))
+                        continue
+                    # @distinct is refused on the object form. It is NOT an engine limit
+                    # (both engines dedupe JSON objects); it is a guaranteed no-op
+                    # whenever the value object carries the entity's primary key, which
+                    # is the common case, and a silent no-op is worse than a refusal.
+                    if has_distinct:
+                        errors.append(MetaError(
+                            f"origin.aggregate @agg:collect on {obj.name}.{node.name}: @distinct "
+                            f"is not supported on a whole-object rollup (it is a no-op whenever "
+                            f"the value object carries the primary key).",
+                            ErrorCode.ERR_COLLECT_WHOLE_OBJECT, envelope=src))
+                        continue
+                    # One walk yields both the hops (cardinality) and the terminal entity
+                    # (@orderBy keys, member resolution). An invalid @via (e.g. a single-
+                    # segment "A") returns None having already pushed its own error, so
+                    # everything downstream is skipped and no second, misleadingly-scoped
+                    # error is emitted.
+                    walked = _validate_via_path(
+                        via_attr, ctx, root, host_pkg, errors, origin, referrer)
+                    if walked is not None:
+                        _check_aggregate_cardinality(walked.hops, node.name, src, errors)
+                        # @orderBy keys resolve against the @via TERMINAL entity, not @of.
+                        _validate_order_by_keys(
+                            order_by, walked.terminal, obj, node.name,
+                            "origin.aggregate @agg:collect", src, errors,
+                            ErrorCode.ERR_COLLECT_WHOLE_OBJECT)
+                        if ref_target is not None:
+                            _check_collect_members(
+                                ref_target, walked.terminal, obj, node, src, errors)
                     continue
                 # NOTE (FR-024 B6): NO extends/origin agreement on aggregates —
                 # an aggregate computes something new (spec §4 is passthrough-only).
@@ -2261,7 +2419,8 @@ def _validate_origin_paths(
                         obj, node.name, "origin.aggregate @agg:collect", src, errors)
                 via = origin.attr(ORIGIN_ATTR_VIA)
                 if isinstance(via, str) and via:
-                    hops = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                    walked = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                    hops = walked.hops if walked is not None else None
                     if hops is not None:
                         _check_aggregate_cardinality(hops, node.name, src, errors)
                     continue
@@ -2372,7 +2531,8 @@ def _validate_origin_paths(
                 # @via — explicit (validated + cardinality) or single-hop-unique inferred.
                 via = origin.attr(ORIGIN_ATTR_VIA)
                 if isinstance(via, str) and via:
-                    hops = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                    walked = _validate_via_path(via, ctx, root, host_pkg, errors, origin, referrer)
+                    hops = walked.hops if walked is not None else None
                     if hops is not None:
                         _check_aggregate_cardinality(hops, node.name, src, errors)
                 elif of_target is not None:
@@ -3123,6 +3283,24 @@ def _validate_filterable_has_supported_ops(
         for field in node.fields():
             if field.attrs().get("filterable") is not True:
                 continue
+
+            # #335 Half B — an ARRAY field has no operator band either. Every
+            # FR-009 operator (eq/ne/gt/gte/lt/lte/in/like/isNull) is a scalar
+            # comparison; none applies to a collection column. Same reason as
+            # the subtype check below, so same code.
+            # ADR-0039: resolved_is_array(), never the own `is_array` flag.
+            if field.resolved_is_array():
+                errors.append(
+                    MetaError(
+                        f'Field "{node.name}.{field.name}" has @filterable: true but is an array '
+                        f"(isArray: true). No filter operator applies to a collection column. "
+                        f"Remove @filterable from this field.",
+                        ErrorCode.ERR_FILTERABLE_UNSUPPORTED_SUBTYPE,
+                        envelope=field.source,
+                    )
+                )
+                continue
+
             if ops_for_subtype(field.sub_type):
                 continue
             errors.append(
@@ -3137,6 +3315,46 @@ def _validate_filterable_has_supported_ops(
             )
 
 
+# ---------------------------------------------------------------------------
+# Pass: @sortable on an array field or unsupported subtype (#335 Half B)
+# ---------------------------------------------------------------------------
+# @sortable defaults FROM @filterable, so it is checked independently only
+# when explicit — nothing validated it before, while @filterable has had a
+# hard error since SP-H Unit9. A @sortable JSON or array column emits a sort
+# entry over a column no dialect can ORDER BY meaningfully.
+# → ERR_SORTABLE_UNSUPPORTED_SUBTYPE.
+
+
+def _validate_sortable_has_supported_subtype(
+    root: MetaData,
+    errors: list[MetaError],
+) -> None:
+    for node in _walk(root):
+        if node.type != TYPE_OBJECT or not isinstance(node, MetaObject):
+            continue
+        for field in node.fields():
+            if field.attrs().get(FIELD_ATTR_SORTABLE) is not True:
+                continue
+            # ADR-0039: resolved_is_array(), never the own `is_array` flag.
+            is_array = field.resolved_is_array()
+            if not is_array and ops_for_subtype(field.sub_type):
+                continue
+
+            reason = (
+                "is an array (isArray: true) — a collection column has no ordering."
+                if is_array
+                else f'its subtype "{field.sub_type}" cannot be ordered.'
+            )
+            errors.append(
+                MetaError(
+                    f'Field "{node.name}.{field.name}" has @sortable: true but {reason} '
+                    f"Remove @sortable from this field.",
+                    ErrorCode.ERR_SORTABLE_UNSUPPORTED_SUBTYPE,
+                    envelope=field.source,
+                )
+            )
+
+
 # ---------------------------------------------------------------------------
 # Pass: field.object @storage validation
 # ---------------------------------------------------------------------------
@@ -3509,12 +3727,22 @@ def _parse_string_list(raw: object) -> tuple[str, ...]:
 
 
 # ---------------------------------------------------------------------------
-# Pass: index.lookup @fields resolution
+# Pass: index-key resolution for index.lookup AND identity.secondary (#342)
+#
+# The key is @fields XOR @expr. @expr has always been registered as "used
+# INSTEAD of @fields" and migrate-ts has always keyed off it
+# (`columns: expr ? [] : cols`), but the loader required @fields
+# unconditionally — so an expression index could not be declared, and the one
+# spelling that DID load (@fields AND @expr) had its @fields silently discarded
+# downstream. Declaring both is now refused rather than half-honored, which is
+# the silent-wrong-output the sealed strict registry exists to prevent.
+#
+# identity.secondary is included because per ADR-0040 uniqueness lives in the
+# TYPE — identity.secondary IS a unique index and keys itself identically,
+# carrying @expr from the same db provider.
 #
-# Every index.lookup on an entity must name at least one field, and every
-# named field must exist in the entity's EFFECTIVE (resolved) field set.
-# ADR-0039: use children() / MetaIndex.fields() — never own* — so that a
-# field inherited via extends still resolves correctly.
+# ADR-0039: children() / MetaIndex.fields() — never own* — so a field inherited
+# via extends still resolves correctly.
 # ---------------------------------------------------------------------------
 
 def _validate_index_lookup_fields(root: MetaData, errors: list[MetaError]) -> None:
@@ -3525,30 +3753,77 @@ def _validate_index_lookup_fields(root: MetaData, errors: list[MetaError]) -> No
             f.name for f in obj.children() if f.type == TYPE_FIELD
         }
         for node in obj.children():
-            if node.type != TYPE_INDEX or node.sub_type != INDEX_SUBTYPE_LOOKUP:
+            is_lookup = node.type == TYPE_INDEX and node.sub_type == INDEX_SUBTYPE_LOOKUP
+            is_secondary = (
+                node.type == TYPE_IDENTITY
+                and node.sub_type == IDENTITY_SUBTYPE_SECONDARY
+            )
+            if not (is_lookup or is_secondary):
                 continue
-            if not isinstance(node, MetaIndex):
+            label = f"{node.type}.{node.sub_type}"
+            # PRESENCE vs CONTENT are two different questions, and conflating them is
+            # a bug in both directions. The CONTRADICTION check needs PRESENCE — an
+            # explicit `@fields: []` beside @expr is still a declaration of both, and
+            # keying it on non-emptiness let that spelling load clean while
+            # `@fields: ["x"]` + @expr was refused. The KEY-RESOLUTION check needs
+            # normalized CONTENT, which folds absent/scalar/empty together — the
+            # normalization is the fix for one and the obstacle for the other, so the
+            # two questions are asked separately. attrs() is the RESOLVING accessor in
+            # Python (attr() is own-only — ADR-0039).
+            attrs = node.attrs()
+            has_fields_attr = IDENTITY_ATTR_FIELDS in attrs
+            if isinstance(node, MetaIndex):
+                fields = node.fields()
+            else:
+                raw = attrs.get(IDENTITY_ATTR_FIELDS)
+                fields = list(raw) if isinstance(raw, (list, tuple)) else []
+            expr = attrs.get(IDENTITY_ATTR_EXPR)
+            has_expr = isinstance(expr, str) and expr.strip() != ""
+
+            # Rule 1a: exactly one of @fields / @expr may be DECLARED.
+            if has_fields_attr and has_expr:
+                errors.append(MetaError(
+                    code=ErrorCode.ERR_INVALID_INDEX,
+                    message=(
+                        f'{label} "{node.name}" on "{obj.name}" declares BOTH '
+                        f"@{INDEX_ATTR_FIELDS} and @{IDENTITY_ATTR_EXPR}; they are the "
+                        f"two mutually exclusive ways to key an index. "
+                        f"@{IDENTITY_ATTR_EXPR} is used INSTEAD of @{INDEX_ATTR_FIELDS} "
+                        f"— drop one. (Declaring both previously loaded but silently "
+                        f"discarded @{INDEX_ATTR_FIELDS}.)"
+                    ),
+                    envelope=node.source,
+                ))
                 continue
-            fields = node.fields()
 
-            if len(fields) == 0:
+            # Rule 1b: whichever is declared must actually supply a key.
+            # envelope=node.source — FR5a/ADR-0009 provenance. TS, Java and C# have
+            # always attached it here; Python did not, so these errors arrived with an
+            # empty envelope. The cross-port corpus asserts envelope SHAPE, which is
+            # what surfaced it.
+            if len(fields) == 0 and not has_expr:
                 errors.append(MetaError(
                     code=ErrorCode.ERR_INVALID_INDEX,
                     message=(
-                        f'index.lookup "{node.name}" on "{obj.name}" has no '
-                        f"@{INDEX_ATTR_FIELDS}; at least one field is required"
+                        f'{label} "{node.name}" on "{obj.name}" declares no key: '
+                        f"it must have @{INDEX_ATTR_FIELDS} (one or more columns) "
+                        f"or @{IDENTITY_ATTR_EXPR} (a key expression)"
                     ),
+                    envelope=node.source,
                 ))
                 continue
 
+            # Rule 2: every named field must resolve. An @expr index has no
+            # @fields to resolve — @expr is raw SQL, deliberately not parsed here.
             for field_name in fields:
                 if field_name not in effective_field_names:
                     errors.append(MetaError(
                         code=ErrorCode.ERR_INVALID_INDEX,
                         message=(
-                            f'index.lookup "{node.name}" on "{obj.name}" references '
+                            f'{label} "{node.name}" on "{obj.name}" references '
                             f'field "{field_name}" which does not exist on "{obj.name}". '
                             f"Available fields: "
                             f"{', '.join(sorted(effective_field_names)) or '(none)'}"
                         ),
+                        envelope=node.source,
                     ))

{metaobjects-0.24.0 → metaobjects-0.24.1}/src/metaobjects/registry_manifest.py

@@ -255,7 +255,7 @@ def _sorted_children(definition: TypeDefinition) -> list[dict[str, object]]:
     return children
 
 
-METAMODEL_VERSION = "0.10"
+METAMODEL_VERSION = "0.12"
 """Rolled-up spec-version for the cross-port registry manifest.
 
 ``"0"`` = pre-1.0 / unstable (semver major-0). Flips to ``"1.0"`` at the

{metaobjects-0.24.0 → metaobjects-0.24.1}/src/metaobjects/spec_metamodel/identity.json

@@ -19,7 +19,7 @@
       "description": "A secondary unique index on one or more fields. Always enforces uniqueness — use index.lookup for non-unique query-performance indexes.",
       "whenToUse": "A column or set of columns must be unique (e.g. email, slug, composite business key). For a plain non-unique index, use index.lookup instead.",
       "children": [
-        { "type": "attr", "subType": "string", "name": "fields", "isArray": true, "min": 1, "max": 1, "description": "The field name(s) composing this identity. Single-element for a simple unique index, multiple for a composite unique constraint." }
+        { "type": "attr", "subType": "string", "name": "fields", "isArray": true, "min": 0, "max": 1, "description": "The field name(s) composing this identity. Single-element for a simple unique index, multiple for a composite unique constraint. Required UNLESS @expr is present — a unique index keys off plain columns (@fields) or a key expression (@expr), never both; declaring both is ERR_INVALID_INDEX." }
       ]
     },
     {

{metaobjects-0.24.0 → metaobjects-0.24.1}/src/metaobjects/spec_metamodel/index.json

@@ -7,7 +7,7 @@
       "description": "A non-unique lookup index on one or more fields. Use for query-performance indexes that do NOT enforce uniqueness — declare identity.secondary for unique constraints instead.",
       "whenToUse": "You need a DB index for query performance (fast lookups/sorts) but NOT uniqueness enforcement. @fields names the indexed columns; the db provider adds @orders / @expr / @where / @using for physical tuning.",
       "children": [
-        { "type": "attr", "subType": "string", "name": "fields", "isArray": true, "min": 1, "max": 1, "description": "The field name(s) this index covers (at least one). When @expr is present, it is the key expression derived from these fields." }
+        { "type": "attr", "subType": "string", "name": "fields", "isArray": true, "min": 0, "max": 1, "description": "The field name(s) this index covers. Required UNLESS @expr is present — an index keys off plain columns (@fields) or a key expression (@expr), never both; declaring both is ERR_INVALID_INDEX." }
       ]
     }
   ]

{metaobjects-0.24.0 → metaobjects-0.24.1}/src/metaobjects/spec_metamodel/origin.json

@@ -20,15 +20,15 @@
     {
       "type": "origin",
       "subType": "aggregate",
-      "description": "A value reduced from the related row-set reached along a relationship path (@via) from the base entity: count/sum/avg/min/max over a column (@of); any/all predicate quantifiers over a @filter; or collect (an array rollup of @of).",
+      "description": "A value reduced from the related row-set reached along a relationship path (@via) from the base entity: count/sum/avg/min/max over a column (@of); any/all predicate quantifiers over a @filter; or collect (an array rollup — of the @of column, or of the carrying field.object's declared @objectRef value object when @of is omitted).",
       "whenToUse": "A projection needs a value derived by reducing related rows — a count/sum/avg/min/max, a 'did any/every related row match' flag, or an array of collected values. Declare it instead of hand-writing the aggregate query — it stays consistent and regenerates.",
-      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly. @of is required for count/sum/avg/min/max/collect and forbidden for any/all (which quantify over rows via @filter, not a column). @filter is required for any/all. The field must be isArray:true for collect and isArray:false for every other @agg. @distinct and @orderBy are collect-only.",
+      "rules": "@via may be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (single-hop-unique inference; FR-024, ADR-0029). Multi-hop paths must always be stated explicitly. @of is required for count/sum/avg/min/max and forbidden for any/all (which quantify over rows via @filter, not a column). @filter is required for any/all. The field must be isArray:true for collect and isArray:false for every other @agg. @distinct and @orderBy are collect-only. On @agg:collect @of is OPTIONAL: omitting it declares a WHOLE-OBJECT rollup, which collects each related row as the carrying field's declared @objectRef value object instead of one scalar column. A whole-object rollup requires a field.object carrying @objectRef, requires that @objectRef to name an object.value, requires an explicit @via (there is no @of entity to infer the path from), and refuses @distinct. Its @orderBy keys resolve against the @via TERMINAL entity, not the head or a middle hop. Its value-object members bind to the terminal entity's fields BY NAME — member name == terminal field name, deliberately NOT extends, so one value object stays collectable from two different entities — and every member must match a terminal field agreeing on BOTH field.<subType> and array-ness.",
       "children": [
-        { "type": "attr", "subType": "string", "name": "agg", "min": 1, "max": 1, "allowedValues": ["count", "sum", "avg", "min", "max", "any", "all", "collect"], "description": "The reducing function applied over the related row-set: count/sum/avg/min/max (numeric/ordinal reduces over @of); any/all (predicate quantifiers over @filter — @of forbidden; empty set → any=false, all=true); collect (array rollup of @of — the field must be isArray)." },
-        { "type": "attr", "subType": "string", "name": "of", "min": 0, "max": 1, "description": "Dotted Entity.field reference identifying the column being aggregated (e.g. 'Week.durationMinutes'). Required for count/sum/avg/min/max/collect; forbidden for any/all (which quantify over rows via @filter, not a column)." },
+        { "type": "attr", "subType": "string", "name": "agg", "min": 1, "max": 1, "allowedValues": ["count", "sum", "avg", "min", "max", "any", "all", "collect"], "description": "The reducing function applied over the related row-set: count/sum/avg/min/max (numeric/ordinal reduces over @of); any/all (predicate quantifiers over @filter — @of forbidden; empty set → any=false, all=true); collect (array rollup — of the @of column, or of the carrying field.object's declared @objectRef value object when @of is omitted; the field must be isArray)." },
+        { "type": "attr", "subType": "string", "name": "of", "min": 0, "max": 1, "description": "Dotted Entity.field reference identifying the column being aggregated (e.g. 'Week.durationMinutes'). Required for count/sum/avg/min/max; OPTIONAL for collect, where absent means a whole-object rollup of the field's declared @objectRef value object; forbidden for any/all (which quantify over rows via @filter, not a column)." },
         { "type": "attr", "subType": "string", "name": "via", "min": 0, "max": 1, "description": "Dotted relationship path from the base entity to the aggregated rows (e.g. 'Program.weeks' or 'Program.weeks.workouts'). May be omitted only when exactly one single-hop relationship leads from the base entity to the @of entity (FR-024, ADR-0029)." },
         { "type": "attr", "subType": "filter", "name": "filter", "min": 0, "max": 1, "description": "Optional structured predicate scoping which related rows the aggregate spans (required for any/all, where it is the quantified predicate). A portable attr.filter object (eq/ne/in/isNull with and/or), desugared to canonical { field: { op: value } } at parse time; codegen renders it per target (e.g. SQL FILTER (WHERE ...) or SQLite CASE WHEN for a relational view)." },
-        { "type": "attr", "subType": "boolean", "name": "distinct", "min": 0, "max": 1, "description": "Set (collect-only) to dedupe collected values (set semantics)." },
+        { "type": "attr", "subType": "boolean", "name": "distinct", "min": 0, "max": 1, "description": "Set (collect-only) to dedupe collected values (set semantics). Not supported on a whole-object collect (@of omitted): it is a guaranteed no-op whenever the value object carries the primary key, and a silent no-op is worse than a refusal." },
         { "type": "attr", "subType": "string", "name": "orderBy", "isArray": true, "min": 0, "max": 1, "description": "Ordering keys as 'field[:asc|desc]' (default asc) over the related entity's fields; nulls sort last. On @agg:collect sets element order (non-distinct only); on origin.first (required) selects the row. Semantic — carries no SQL syntax." }
       ]
     },

{metaobjects-0.24.0 → metaobjects-0.24.1}/uv.lock

@@ -250,7 +250,7 @@ wheels = [
 
 [[package]]
 name = "metaobjects"
-version = "0.23.2"
+version = "0.24.1"
 source = { editable = "." }
 dependencies = [
     { name = "pyyaml" },