fix(metamodel): the index key is @fields XOR @expr, in all five ports (#342)

`@expr` was registered, built and rendered — and unreachable. The registry has always
described it as "Used INSTEAD of @fields", migrate-ts has always keyed off it
(`columns: expr ? [] : cols`), the Postgres emitter has always rendered it, and
introspection has always read expression keys back via pg_get_expr. Only the LOADER
disagreed, requiring @fields unconditionally. So: @expr alone failed to load on both
node types, and the one spelling that DID load — @fields AND @expr — had its @fields
silently discarded downstream. An expression index had to be kept as hand-written SQL
outside the migration ledger, which then read as permanent `verify --db` drift.

The rule is now stated once and enforced once. Neither is an error, as before; BOTH is
now also an error rather than accepted-and-half-honored. Failing closed matches the
sealed-strict posture and the ERR_SQL_BODY_WITH_UNMANAGED precedent — @SQL vs
@Unmanaged is the same "two mutually exclusive non-default states of one axis" shape.

PATCH, not MINOR: a declaration that loaded while silently throwing half of itself away
was never validly expressible, so refusing it corrects previously-wrong acceptance
rather than changing a contract — the same call as the @min clamp in 0.19.1 and the
`like` case-sensitivity fix in 0.21.6. metamodelVersion moves 0.10 -> 0.11 (@fields
becomes optional on both types, which the gate classifies as additive); the package
line stays a patch, which is what ADR-0035 Am. 2 severed the two numbers for.

Covers identity.secondary as well as index.lookup: per ADR-0040 uniqueness lives in the
TYPE, so identity.secondary IS a unique index, keys itself identically, and carries
@expr from the same db provider. identity.primary / identity.reference are untouched —
a primary key or an FK is always plain columns and has no @expr at all.

TWO CROSS-PORT DIVERGENCES THE NEW FIXTURE FOUND, THAT NO PORT'S OWN SUITE DID.
Java carried a BESPOKE @fields requirement in ValidationPhase.validateIdentityNode,
applied to every identity independently of the registry — so relaxing the schema tier
left Java alone refusing metadata the other three accepted. And Python emitted its
index errors with an EMPTY provenance envelope while TS/Java/C# attached node.source;
the corpus asserts envelope shape, which is what surfaced it.

Gated by two shared fixtures — index-expr-keys-without-fields (both node types keyed by
expression) and error-index-fields-and-expr — plus per-port tests. The positive fixture
asserts a CLEAN load, not merely the absence of one error code: the weaker assertion
passed while the child-rule check still refused it under a different code, which is how
this reached an adopter. Proved by reverting the fix and watching it go red.

Also folds in a one-line uv.lock catch-up left stale by the 0.24.0 version bump.

TS 2481 · Java 1470 · Python 1837 · C# 1672 — all green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DhpswkF1NvwxhFWMmdAT15

Author: dmealing

CHANGELOG.md

@@ -7,6 +7,59 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.24.1] — npm `0.24.1` · PyPI `0.24.1` · NuGet `0.24.1` · Maven `7.24.1`
+
+### Fixed — an expression index was undeclarable, and the one spelling that loaded was half-ignored ([#342](https://github.com/metaobjectsdev/metaobjects/issues/342))
+
+**`@expr` was registered, built and rendered — and unreachable.** The registry has always
+described it as *"Used **INSTEAD of** `@fields`"*, `migrate-ts` has always keyed off it
+(`columns: expr ? [] : cols`), the Postgres emitter has always rendered it, and
+introspection has always read expression keys back via `pg_get_expr`. Only the **loader**
+disagreed, requiring `@fields` unconditionally. So the three-row matrix an adopter hit was:
+
+| Node | attrs | Before |
+|---|---|---|
+| `index.lookup` | `@expr` only | ❌ fails to load |
+| `identity.secondary` | `@expr` only | ❌ fails to load |
+| either | `@fields` **+** `@expr` | ⚠️ loads — and `@fields` is **silently discarded** |
+
+An expression index therefore had to live as hand-written SQL outside the migration
+ledger, which then reported as permanent `verify --db` drift.
+
+**The rule is now stated once and enforced once: the index key is `@fields` XOR `@expr`.**
+Declaring neither is an error (as before); declaring **both is now also an error**
+(`ERR_INVALID_INDEX`) rather than being accepted and half-honored. Failing closed matches
+the sealed-strict-registry posture and the existing `ERR_SQL_BODY_WITH_UNMANAGED`
+precedent — `@sql` vs `@unmanaged` is the same "two mutually exclusive non-default states
+of one axis" shape. **This is a PATCH, not a MINOR:** a declaration that loaded while
+silently throwing half of itself away was never validly expressible, so refusing it
+corrects previously-wrong acceptance rather than changing a contract — the same call, for
+the same reason, as the `@min` clamp in `0.19.1` and the `like` case-sensitivity fix in
+`0.21.6`.
+
+**Applies to `identity.secondary` as well as `index.lookup`**, because per
+[ADR-0040](spec/decisions/ADR-0040-index-type-and-secondary-key-purity.md) uniqueness
+lives in the TYPE — `identity.secondary` IS a unique index, keys itself identically, and
+carries `@expr` from the same db provider. `identity.primary` and `identity.reference` are
+untouched: a primary key or an FK is always plain columns and carries no `@expr` at all.
+
+**`metamodelVersion` moves `0.10` → `0.11`** — `@fields` becomes optional on both node
+types, which the gate classifies as additive. The package line stays a PATCH; that
+severance is exactly what [ADR-0035 Amendment 2](docs/RELEASING.md) is for, and post-1.0
+the changelog is the only signal on the metadata axis.
+
+**Two things this took, worth recording.** The Java port needed a fix the other three did
+not: beyond the registry declaration, `ValidationPhase.validateIdentityNode` carried a
+**bespoke, Java-only** `@fields` requirement applied to every identity, so relaxing the
+schema tier alone left Java refusing metadata that TypeScript, C# and Python accepted —
+found by the new cross-port fixture, not by any port's own suite. And Python's index
+errors were emitted with an **empty provenance envelope** while the other three attached
+`node.source`; the corpus asserts envelope shape, which is what surfaced it.
+
+Gated by two new shared conformance fixtures — `index-expr-keys-without-fields` (both node
+types keyed by expression, loads clean) and `error-index-fields-and-expr` — plus per-port
+tests. All five ports green.
+
 ## [0.24.0] — npm `0.24.0` · PyPI `0.24.0` · NuGet `0.24.0` · Maven `7.24.0`
 
 > ### ⚠️ BREAKING FOR METADATA AUTHORS — five vocabulary changes in ONE window

fixtures/conformance/error-index-fields-and-expr/expected-errors.json

@@ -0,0 +1,15 @@
+{
+  "errors": [
+    {
+      "code": "ERR_INVALID_INDEX",
+      "source": {
+        "format": "json",
+        "files": [
+          "meta.demo.json"
+        ],
+        "jsonPath": "$['metadata.root'].children[0]['object.entity'].children[5]['index.lookup']"
+      }
+    }
+  ],
+  "warnings": []
+}

fixtures/conformance/error-index-fields-and-expr/input/meta.demo.json

@@ -0,0 +1,27 @@
+{
+  "metadata.root": {
+    "package": "demo::indexing",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Notification",
+          "children": [
+            { "source.rdb": { "@table": "notifications" } },
+            { "field.string": { "name": "id", "@required": true } },
+            { "field.timestamp": { "name": "deliveredAt" } },
+            { "field.string": { "name": "payload" } },
+            { "identity.primary": { "name": "pk", "@fields": ["id"] } },
+
+            {
+              "index.lookup": {
+                "name": "bothIdx",
+                "@fields": ["deliveredAt"],
+                "@expr": "(payload->>'device_id')"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/error-index-fields-and-expr/providers.json

@@ -0,0 +1 @@
+["metaobjects-core-types","metaobjects-db"]

fixtures/conformance/index-expr-keys-without-fields/expected.json

@@ -0,0 +1,57 @@
+{
+  "metadata.root": {
+    "package": "demo::indexing",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Notification",
+          "children": [
+            {
+              "source.rdb": {
+                "@table": "notifications"
+              }
+            },
+            {
+              "field.string": {
+                "name": "id",
+                "@required": true
+              }
+            },
+            {
+              "field.timestamp": {
+                "name": "deliveredAt"
+              }
+            },
+            {
+              "field.string": {
+                "name": "payload"
+              }
+            },
+            {
+              "identity.primary": {
+                "name": "pk",
+                "@fields": [
+                  "id"
+                ]
+              }
+            },
+            {
+              "index.lookup": {
+                "name": "pendingDeviceIdx",
+                "@expr": "(payload->>'device_id')",
+                "@where": "delivered_at IS NULL"
+              }
+            },
+            {
+              "identity.secondary": {
+                "name": "lowerIdUk",
+                "@expr": "lower(id)"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+

fixtures/conformance/index-expr-keys-without-fields/input/meta.demo.json

@@ -0,0 +1,34 @@
+{
+  "metadata.root": {
+    "package": "demo::indexing",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Notification",
+          "children": [
+            { "source.rdb": { "@table": "notifications" } },
+            { "field.string": { "name": "id", "@required": true } },
+            { "field.timestamp": { "name": "deliveredAt" } },
+            { "field.string": { "name": "payload" } },
+            { "identity.primary": { "name": "pk", "@fields": ["id"] } },
+
+            {
+              "index.lookup": {
+                "name": "pendingDeviceIdx",
+                "@expr": "(payload->>'device_id')",
+                "@where": "delivered_at IS NULL"
+              }
+            },
+
+            {
+              "identity.secondary": {
+                "name": "lowerIdUk",
+                "@expr": "lower(id)"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/index-expr-keys-without-fields/providers.json

@@ -0,0 +1 @@
+["metaobjects-core-types","metaobjects-db"]

fixtures/metamodel-docs/expected/types/identity.md

@@ -65,7 +65,7 @@ A secondary unique index on one or more fields. Always enforces uniqueness — u
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
 | --- | --- | --- | --- | --- | --- | --- |
 | `@expr` | string | no |  |  | metaobjects-db | 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. |
-| `@fields` | string[] | yes |  |  | metaobjects-core-types | The field name(s) composing this identity. Single-element for a simple unique index, multiple for a composite unique constraint. |
+| `@fields` | string[] | no |  |  | metaobjects-core-types | 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. |
 | `@orders` | string[] | no |  | `asc`, `desc` | metaobjects-db | 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, not core identity. |
 | `@using` | string | no |  |  | metaobjects-db | 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. |
 | `@where` | string | no |  |  | metaobjects-db | 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. |

fixtures/metamodel-docs/expected/types/index.md

@@ -21,7 +21,7 @@ A non-unique lookup index on one or more fields. Use for query-performance index
 | Attribute | Type | Required | Default | Allowed values | Provider | Description |
 | --- | --- | --- | --- | --- | --- | --- |
 | `@expr` | string | no |  |  | metaobjects-db | 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. |
-| `@fields` | string[] | yes |  |  | — | The field name(s) this index covers (at least one). When @expr is present, it is the key expression derived from these fields. |
+| `@fields` | string[] | no |  |  | — | 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. |
 | `@orders` | string[] | no |  | `asc`, `desc` | metaobjects-db | 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. |
 | `@using` | string | no |  |  | metaobjects-db | 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. |
 | `@where` | string | no |  |  | metaobjects-db | 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. |

fixtures/registry-conformance/expected-registry.json

@@ -1,5 +1,5 @@
 {
-  "metamodelVersion": "0.10",
+  "metamodelVersion": "0.11",
   "types": [
     {
       "type": "attr",
@@ -2924,8 +2924,8 @@
           "name": "fields",
           "valueType": "string",
           "isArray": true,
-          "required": true,
-          "description": "The field name(s) composing this identity. Single-element for a simple unique index, multiple for a composite unique constraint."
+          "required": false,
+          "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."
         },
         {
           "name": "orders",
@@ -2972,8 +2972,8 @@
           "name": "fields",
           "valueType": "string",
           "isArray": true,
-          "required": true,
-          "description": "The field name(s) this index covers (at least one). When @expr is present, it is the key expression derived from these fields."
+          "required": false,
+          "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."
         },
         {
           "name": "orders",