metaobjects 0.15.0__tar.gz → 0.15.1__tar.gz

{metaobjects-0.15.0 → metaobjects-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: metaobjects
-Version: 0.15.0
+Version: 0.15.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.15.0 → metaobjects-0.15.1}/pyproject.toml

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

@@ -42,7 +42,6 @@ from .meta.core.identity.identity_constants import (
     GENERATION_VALUES,
     IDENTITY_ATTR_FIELDS,
     IDENTITY_ATTR_GENERATION,
-    IDENTITY_ATTR_UNIQUE,
     IDENTITY_REFERENCE_ATTR_ENFORCE,
     IDENTITY_REFERENCE_ATTR_REFERENCES,
     IDENTITY_SUBTYPE_PRIMARY,
@@ -50,6 +49,8 @@ from .meta.core.identity.identity_constants import (
     IDENTITY_SUBTYPE_SECONDARY,
 )
 from .meta.core.identity.meta_identity import MetaIdentity
+from .meta.core.index.index_constants import INDEX_ATTR_FIELDS, INDEX_SUBTYPE_LOOKUP, INDEX_SUBTYPES
+from .meta.core.index.meta_index import MetaIndex
 from .meta.core.object.meta_object import MetaObject
 from .meta.core.object.object_constants import (
     OBJECT_ATTR_DISCRIMINATOR,
@@ -117,6 +118,7 @@ from .shared.base_types import (
     TYPE_ATTR,
     TYPE_FIELD,
     TYPE_IDENTITY,
+    TYPE_INDEX,
     TYPE_LAYOUT,
     TYPE_METADATA,
     TYPE_OBJECT,
@@ -195,10 +197,12 @@ core_provider.add(
     )
 )
 
+
 # object.* (entity, value, projection)
 _OBJECT_CHILD_RULES = [
     ChildRule(TYPE_FIELD, "*"),
     ChildRule(TYPE_IDENTITY, "*"),
+    ChildRule(TYPE_INDEX, "*"),
     ChildRule(TYPE_ATTR, "*"),
     ChildRule(TYPE_SOURCE, "*"),
     ChildRule(TYPE_RELATIONSHIP, "*"),
@@ -436,8 +440,9 @@ core_provider.add(
     )
 )
 
-# identity.secondary — @fields required stringArray; @unique optional boolean
-# (true → UNIQUE index, false → plain index). Cross-port; mirrors TS secondaryIdentityAttrs.
+# identity.secondary — @fields required stringArray. Always enforces uniqueness;
+# use index.lookup for non-unique indexes. @unique is no longer a core attr
+# (removed — the secondary index is always unique by definition).
 core_provider.add(
     TypeDefinition(
         type=TYPE_IDENTITY,
@@ -445,7 +450,6 @@ core_provider.add(
         factory=MetaIdentity,
         attrs=[
             AttrSchema(name=IDENTITY_ATTR_FIELDS, value_type=ATTR_SUBTYPE_STRING, required=True, is_array=True),
-            AttrSchema(name=IDENTITY_ATTR_UNIQUE, value_type=ATTR_SUBTYPE_BOOLEAN, required=False),
         ],
         child_rules=[ChildRule(TYPE_ATTR, "*")],
     )
@@ -470,6 +474,22 @@ core_provider.add(
     )
 )
 
+# index.lookup — non-unique lookup index on one or more fields.
+# Distinct from identity.secondary (which always enforces uniqueness).
+# Physical attrs (@orders/@expr/@where/@using) are contributed by the db provider.
+for _idx_sub in INDEX_SUBTYPES:
+    core_provider.add(
+        TypeDefinition(
+            type=TYPE_INDEX,
+            sub_type=_idx_sub,
+            factory=MetaIndex,
+            attrs=[
+                AttrSchema(name=INDEX_ATTR_FIELDS, value_type=ATTR_SUBTYPE_STRING, required=True, is_array=True),
+            ],
+            child_rules=[ChildRule(TYPE_ATTR, "*")],
+        )
+    )
+
 # relationship.* (base, association, aggregation, composition).
 # @onDelete / @onUpdate are validated against REFERENTIAL_ACTIONS — kebab-case
 # values (cascade / set-null / restrict / no-action). Defaults derive from the

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/errors.py

@@ -77,6 +77,7 @@ class ErrorCode(str, Enum):
     # FR-017 — M:N relationship slim-vocabulary validation (junction-missing-two-
     # references / sourceRefField-not-matching / M:N-attr-on-1:N). The symmetric-
     # on-hetero + symmetric+sourceRefField rules emit ERR_BAD_ATTR_VALUE instead.
+    ERR_INVALID_INDEX = "ERR_INVALID_INDEX"
     ERR_INVALID_RELATIONSHIP = "ERR_INVALID_RELATIONSHIP"
     # identity.reference @references names an FK target object that does not resolve
     # to any object in the loaded tree (a dangling cross-reference between metadata).

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/loader/validation_passes.py

@@ -63,6 +63,7 @@ from ..registry import AttrSchema, ChildRule, TypeRegistry
 from ..shared.base_types import (
     TYPE_FIELD,
     TYPE_IDENTITY,
+    TYPE_INDEX,
     TYPE_LAYOUT,
     TYPE_OBJECT,
     TYPE_ORIGIN,
@@ -104,6 +105,7 @@ from ..meta.core.object.object_constants import (
     OBJECT_SUBTYPE_VALUE,
 )
 from ..meta.core.identity.identity_constants import IDENTITY_ATTR_FIELDS
+from ..meta.core.index.index_constants import INDEX_ATTR_FIELDS, INDEX_SUBTYPE_LOOKUP
 from ..source import resolved_source
 
 # A subtype-specific template attr is valid ONLY on the subtype it is registered
@@ -184,6 +186,7 @@ def run_validations(
     _validate_filterable_has_index(root, warnings)
     # SP-H Unit9 — @filterable on a subtype with no operator band → error.
     _validate_filterable_has_supported_ops(root, errors)
+    _validate_index_lookup_fields(root, errors)
 
 
 # ---------------------------------------------------------------------------
@@ -459,21 +462,29 @@ def _validate_attr_schema(
             # ERR_BAD_ATTR_VALUE for both an unrecognized value and an illegal
             # pairing. Running the flat membership check too would double-report
             # (tests assert exactly one error). Mirrors the TS reference.
+            #
+            # For array-valued attrs (is_array=True) the raw_value is a list;
+            # check each element individually against allowed_values (e.g.
+            # @orders: ["asc","desc"] — each element must be in {"asc","desc"}).
             if (
                 attr_node.name != FIELD_ATTR_DB_COLUMN_TYPE
                 and schema.allowed_values is not None
                 and len(schema.allowed_values) > 0
             ):
-                if raw_value not in schema.allowed_values:
-                    allowed_str = ", ".join(str(v) for v in schema.allowed_values)
-                    errors.append(
-                        MetaError(
-                            f"{_node_label(node)} attribute '@{attr_node.name}' has value "
-                            f"'{raw_value}' which is not one of the allowed values: {allowed_str}",
-                            ErrorCode.ERR_BAD_ATTR_VALUE,
-                            envelope=node.source,
+                allowed_str = ", ".join(str(v) for v in schema.allowed_values)
+                values_to_check: list = (
+                    list(raw_value) if isinstance(raw_value, list) else [raw_value]
+                )
+                for elem in values_to_check:
+                    if elem not in schema.allowed_values:
+                        errors.append(
+                            MetaError(
+                                f"{_node_label(node)} attribute '@{attr_node.name}' has value "
+                                f"'{elem}' which is not one of the allowed values: {allowed_str}",
+                                ErrorCode.ERR_BAD_ATTR_VALUE,
+                                envelope=node.source,
+                            )
                         )
-                    )
 
 
 # ---------------------------------------------------------------------------
@@ -2448,3 +2459,49 @@ def _parse_string_list(raw: object) -> tuple[str, ...]:
     if isinstance(raw, (list, tuple)):
         return tuple(str(x) for x in raw)
     return ()
+
+
+# ---------------------------------------------------------------------------
+# Pass: index.lookup @fields resolution
+#
+# 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.
+# ---------------------------------------------------------------------------
+
+def _validate_index_lookup_fields(root: MetaData, errors: list[MetaError]) -> None:
+    from ..meta.core.index.meta_index import MetaIndex
+    for obj in (c for c in root.children() if c.type == TYPE_OBJECT):
+        # Effective (resolved) field names — includes inherited fields via extends.
+        effective_field_names = {
+            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:
+                continue
+            if not isinstance(node, MetaIndex):
+                continue
+            fields = node.fields()
+
+            if len(fields) == 0:
+                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"
+                    ),
+                ))
+                continue
+
+            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'field "{field_name}" which does not exist on "{obj.name}". '
+                            f"Available fields: "
+                            f"{', '.join(sorted(effective_field_names)) or '(none)'}"
+                        ),
+                    ))

metaobjects-0.15.1/src/metaobjects/meta/core/index/index_constants.py

@@ -0,0 +1,5 @@
+"""Index subtype + attr vocabulary."""
+INDEX_SUBTYPE_LOOKUP = "lookup"
+INDEX_SUBTYPES = (INDEX_SUBTYPE_LOOKUP,)
+
+INDEX_ATTR_FIELDS = "fields"

metaobjects-0.15.1/src/metaobjects/meta/core/index/meta_index.py

@@ -0,0 +1,15 @@
+"""MetaIndex — concrete node class for type=index nodes."""
+from __future__ import annotations
+
+from ...meta_data import MetaData
+from .index_constants import INDEX_ATTR_FIELDS, INDEX_SUBTYPE_LOOKUP
+
+
+class MetaIndex(MetaData):
+    def fields(self) -> list[str]:
+        """ADR-0039: resolving — @fields may be inherited via extends."""
+        f = self.get_meta_attr(INDEX_ATTR_FIELDS)
+        return list(f) if isinstance(f, list) else []
+
+    def is_lookup(self) -> bool:
+        return self.sub_type == INDEX_SUBTYPE_LOOKUP

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/meta/persistence/db/db_provider.py

@@ -22,9 +22,10 @@ from ...core.identity.identity_constants import (
     IDENTITY_SUBTYPE_REFERENCE,
     IDENTITY_SUBTYPE_SECONDARY,
 )
+from ...core.index.index_constants import INDEX_SUBTYPE_LOOKUP
 from ....provider import Provider
 from ....registry import AttrSchema, TypeRegistry
-from ....shared.base_types import TYPE_FIELD, TYPE_IDENTITY
+from ....shared.base_types import TYPE_FIELD, TYPE_IDENTITY, TYPE_INDEX
 from .db_constants import (
     FIELD_ATTR_DB_COLUMN_TYPE,
     FIELD_ATTR_LOCAL_TIME,
@@ -156,6 +157,12 @@ def _register(registry: TypeRegistry) -> None:
         IDENTITY_SUBTYPE_REFERENCE,
         attributes=[_CONSTRAINT_NAME_SCHEMA],
     )
+    # index.lookup: same RDB physical attrs as identity.secondary (@orders/@where/@expr/@using).
+    registry.extend(
+        TYPE_INDEX,
+        INDEX_SUBTYPE_LOOKUP,
+        attributes=[_ORDERS_SCHEMA, _WHERE_SCHEMA, _EXPR_SCHEMA, _USING_SCHEMA],
+    )
 
 
 def _make_db_provider() -> Provider:

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/shared/base_types.py

@@ -5,6 +5,7 @@ TYPE_FIELD = "field"
 TYPE_ATTR = "attr"
 TYPE_VALIDATOR = "validator"
 TYPE_IDENTITY = "identity"
+TYPE_INDEX = "index"
 TYPE_RELATIONSHIP = "relationship"
 TYPE_VIEW = "view"
 TYPE_LAYOUT = "layout"

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/spec_metamodel/__init__.py

@@ -46,6 +46,7 @@ SPEC_FILES: tuple[str, ...] = (
     "documentation.json",
     "field.json",
     "identity.json",
+    "index.json",
     "layout.json",
     "object.json",
     "origin.json",

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/spec_metamodel/db.json

@@ -62,6 +62,16 @@
       "children": [
         { "type": "attr", "subType": "string", "name": "constraintName", "min": 0, "max": 1, "description": "Physical foreign-key constraint name override. Absent → the backend's auto-derived default (e.g. `<table>_<firstFkColumn>_fk`). Lets a model adopt an existing database whose FK constraints follow a different naming convention without a destructive rename. RDB-physical — contributed by the db provider." }
       ]
+    },
+    {
+      "type": "index",
+      "subType": "lookup",
+      "children": [
+        { "type": "attr", "subType": "string", "name": "orders", "isArray": true, "min": 0, "max": 1, "allowedValues": ["asc", "desc"], "description": "Physical index-key sort direction, positional to @fields ('asc' | 'desc'). Omit for all-ascending (the default); a shorter array leaves trailing keys ascending. Drives DESC-ordered index keys (e.g. a recency index on a timestamp). RDB-physical — contributed by the db provider." },
+        { "type": "attr", "subType": "string", "name": "where", "min": 0, "max": 1, "description": "Partial-index predicate (raw SQL, e.g. \"delivered_at IS NULL\"). When set, the index covers only rows matching the predicate — smaller and cheaper for queries that always filter on it. Absent = a full index over every row. RDB-physical — contributed by the db provider." },
+        { "type": "attr", "subType": "string", "name": "expr", "min": 0, "max": 1, "description": "Raw key EXPRESSION for a functional/expression index (e.g. \"lower(email)\"). Used INSTEAD of @fields — the index key is the expression rather than plain columns. RDB-physical — contributed by the db provider." },
+        { "type": "attr", "subType": "string", "name": "using", "min": 0, "max": 1, "description": "Index access method (e.g. \"gin\", \"gist\", \"hash\"); default \"btree\" (not rendered). Pair with @expr for e.g. a GIN index over an array/jsonb expression. RDB-physical — contributed by the db provider." }
+      ]
     }
   ]
 }

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/spec_metamodel/identity.json

@@ -16,11 +16,10 @@
     {
       "type": "identity",
       "subType": "secondary",
-      "description": "A secondary index (unique by default via @unique).",
-      "whenToUse": "A column or set must be unique, or you want an index for lookups/sorting. Declare it instead of a hand-written UNIQUE constraint or CREATE INDEX.",
+      "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 PK/index, multiple for a composite." },
-        { "type": "attr", "subType": "boolean", "name": "unique", "min": 0, "max": 1, "description": "When true (default), the secondary identity is a UNIQUE index; false makes it a plain (non-unique) index." }
+        { "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." }
       ]
     },
     {

metaobjects-0.15.1/src/metaobjects/spec_metamodel/index.json

@@ -0,0 +1,14 @@
+{
+  "provider": "metaobjects-core-types",
+  "types": [
+    {
+      "type": "index",
+      "subType": "lookup",
+      "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." }
+      ]
+    }
+  ]
+}

{metaobjects-0.15.0 → metaobjects-0.15.1}/src/metaobjects/spec_metamodel/object.json

@@ -10,7 +10,8 @@
         { "type": "identity", "subType": "*", "name": "*", "min": 0, "max": null },
         { "type": "validator", "subType": "*", "name": "*", "min": 0, "max": null },
         { "type": "layout", "subType": "*", "name": "*", "min": 0, "max": null },
-        { "type": "source", "subType": "*", "name": "*", "min": 0, "max": null }
+        { "type": "source", "subType": "*", "name": "*", "min": 0, "max": null },
+        { "type": "index", "subType": "*", "name": "*", "min": 0, "max": null }
       ]
     },
     {

metaobjects-0.15.1/tests/unit/test_index_lookup.py

@@ -0,0 +1,141 @@
+"""Unit tests for index.lookup — load, validation, @unique rejection."""
+from __future__ import annotations
+
+import json
+
+from metaobjects import MetaDataLoader
+from metaobjects.core_types import core_providers
+from metaobjects.errors import ErrorCode
+from metaobjects.meta.core.index.meta_index import MetaIndex
+from metaobjects.shared.base_types import TYPE_INDEX
+
+
+def _load(fixture: dict):
+    content = json.dumps(fixture)
+    return MetaDataLoader.from_string(content, providers=list(core_providers), strict=True)
+
+
+def _simple_entity_with_index(index_body: dict) -> dict:
+    return {
+        "metadata.root": {
+            "package": "test::pkg",
+            "children": [
+                {
+                    "object.entity": {
+                        "name": "Thing",
+                        "children": [
+                            {"field.string": {"name": "name"}},
+                            {"field.long": {"name": "ownerId"}},
+                            {"identity.primary": {"name": "pk", "@fields": ["name"], "@generation": "assigned"}},
+                            {"index.lookup": index_body},
+                        ],
+                    }
+                }
+            ],
+        }
+    }
+
+
+# ---------------------------------------------------------------------------
+# Basic load test
+# ---------------------------------------------------------------------------
+
+def test_index_lookup_loads_successfully():
+    fixture = _simple_entity_with_index({
+        "name": "idx_thing_owner",
+        "@fields": ["ownerId"],
+    })
+    result = _load(fixture)
+    assert not result.errors, f"Unexpected errors: {[e.code for e in result.errors]}"
+    entity = next(c for c in result.root.children() if c.name == "Thing")
+    indexes = [c for c in entity.children() if c.type == TYPE_INDEX]
+    assert len(indexes) == 1
+    idx = indexes[0]
+    assert isinstance(idx, MetaIndex)
+    assert idx.sub_type == "lookup"
+    assert idx.fields() == ["ownerId"]
+
+
+def test_index_lookup_with_orders():
+    fixture = _simple_entity_with_index({
+        "name": "idx_thing_owner_desc",
+        "@fields": ["ownerId"],
+        "@orders": ["desc"],
+    })
+    result = _load(fixture)
+    assert not result.errors, f"Unexpected errors: {[e.code for e in result.errors]}"
+
+
+# ---------------------------------------------------------------------------
+# @unique rejected on identity.secondary (ERR_UNKNOWN_ATTR)
+# ---------------------------------------------------------------------------
+
+def test_unique_rejected_on_identity_secondary():
+    fixture = {
+        "metadata.root": {
+            "package": "test::pkg",
+            "children": [
+                {
+                    "object.entity": {
+                        "name": "Thing",
+                        "children": [
+                            {"field.string": {"name": "email"}},
+                            {"identity.primary": {"name": "pk", "@fields": ["email"], "@generation": "assigned"}},
+                            {
+                                "identity.secondary": {
+                                    "name": "uq_email",
+                                    "@fields": ["email"],
+                                    "@unique": True,
+                                }
+                            },
+                        ],
+                    }
+                }
+            ],
+        }
+    }
+    result = _load(fixture)
+    codes = [e.code for e in result.errors]
+    assert ErrorCode.ERR_UNKNOWN_ATTR in codes, f"Expected ERR_UNKNOWN_ATTR, got: {codes}"
+
+
+# ---------------------------------------------------------------------------
+# @unique rejected on index.lookup (ERR_UNKNOWN_ATTR)
+# ---------------------------------------------------------------------------
+
+def test_unique_rejected_on_index_lookup():
+    fixture = _simple_entity_with_index({
+        "name": "idx_thing_owner",
+        "@fields": ["ownerId"],
+        "@unique": True,
+    })
+    result = _load(fixture)
+    codes = [e.code for e in result.errors]
+    assert ErrorCode.ERR_UNKNOWN_ATTR in codes, f"Expected ERR_UNKNOWN_ATTR, got: {codes}"
+
+
+# ---------------------------------------------------------------------------
+# ERR_INVALID_INDEX: missing @fields
+# ---------------------------------------------------------------------------
+
+def test_index_lookup_missing_fields_emits_err_invalid_index():
+    fixture = _simple_entity_with_index({
+        "name": "idx_bad",
+    })
+    result = _load(fixture)
+    codes = [e.code for e in result.errors]
+    assert ErrorCode.ERR_INVALID_INDEX in codes, f"Expected ERR_INVALID_INDEX, got: {codes}"
+
+
+# ---------------------------------------------------------------------------
+# ERR_INVALID_INDEX: field does not exist on entity
+# ---------------------------------------------------------------------------
+
+def test_index_lookup_unknown_field_emits_err_invalid_index():
+    fixture = _simple_entity_with_index({
+        "name": "idx_bad",
+        "@fields": ["nonExistentField"],
+    })
+    result = _load(fixture)
+    codes = [e.code for e in result.errors]
+    assert ErrorCode.ERR_INVALID_INDEX in codes, f"Expected ERR_INVALID_INDEX, got: {codes}"

{metaobjects-0.15.0 → metaobjects-0.15.1}/uv.lock

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