metaobjectsdev
diff --git a/‎.superpowers/sdd/task-7-report.md‎
Lines changed: 41 additions & 0 deletions b/‎.superpowers/sdd/task-7-report.md‎
Lines changed: 41 additions & 0 deletions
diff --git a/‎.superpowers/sdd/task-9-report.md‎
Lines changed: 63 additions & 0 deletions b/‎.superpowers/sdd/task-9-report.md‎
Lines changed: 63 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 1 addition & 0 deletions b/‎CLAUDE.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎agent-context/skills/metaobjects-authoring/SKILL.md‎
Lines changed: 26 additions & 2 deletions b/‎agent-context/skills/metaobjects-authoring/SKILL.md‎
Lines changed: 26 additions & 2 deletions
diff --git a/‎docs/features/migrations/identity-secondary-to-index-lookup.md‎
Lines changed: 187 additions & 0 deletions b/‎docs/features/migrations/identity-secondary-to-index-lookup.md‎
Lines changed: 187 additions & 0 deletions
@@ -0,0 +1,41 @@
+# Task 7 Report — C# port: index.lookup + drop identity.secondary @unique
+
+## Status: COMPLETE
+
+## Files Created
+
+- `server/csharp/MetaObjects/Core/Index/IndexConstants.cs` — INDEX_SUBTYPE_LOOKUP, INDEX_ATTR_FIELDS constants
+- `server/csharp/MetaObjects/Core/Index/IndexSchema.cs` — AttrSchema for @fields on index.lookup
+- `server/csharp/MetaObjects/Meta/MetaIndex.cs` — MetaIndex node class with Fields() (ADR-0039 resolving accessor)
+- `server/csharp/MetaObjects.Codegen.Tests/IndexLookupTests.cs` — 6 unit tests (happy-path, @unique rejected, ERR_INVALID_INDEX)
+
+## Files Modified
+
+- `server/csharp/MetaObjects/Shared/BaseTypes.cs` — added TYPE_INDEX = "index"
+- `server/csharp/MetaObjects/GlobalUsings.cs` — added `global using static MetaObjects.Core.Index.IndexConstants`
+- `server/csharp/MetaObjects/CoreTypes.cs` — registered index.lookup (TypeDefinition with description+whenToUse), added Wildcard(TYPE_INDEX) to objectRules, added IndexClassMap
+- `server/csharp/MetaObjects/Persistence/Db/DbProvider.cs` — extend index.lookup with @orders/@where/@expr/@using; noted @unique intentionally not extended onto identity.secondary
+- `server/csharp/MetaObjects/Core/Identity/IdentityConstants.cs` — removed IDENTITY_ATTR_UNIQUE constant
+- `server/csharp/MetaObjects/Core/Identity/IdentitySchema.cs` — removed @unique from SecondaryIdentityAttrs
+- `server/csharp/MetaObjects/Meta/MetaIdentity.cs` — removed Unique property
+- `server/csharp/MetaObjects/Errors.cs` — added ERR_INVALID_INDEX
+- `server/csharp/MetaObjects/Loader/ValidationPasses.cs` — added ValidateIndexLookupFields; also fixed array-valued allowedValues check (Check 3) to validate each element rather than the whole array (bug discovered: @orders ["asc","desc"] was triggering ERR_BAD_ATTR_VALUE)
+- `server/csharp/MetaObjects/Loader/MetaDataLoader.cs` — wired ValidateIndexLookupFields into load pipeline
+- `server/csharp/MetaObjects/SpecMetamodel/*.json` — copied updated spec files (object.json now has index.* child rule)
+
+## Key Fix: allowedValues array element validation
+
+The existing C# Check 3 (allowedValues membership) compared the entire array value against allowed values, which caused `ERR_BAD_ATTR_VALUE` for `@orders: ["asc", "desc"]` on `index.lookup`. Fixed to validate each element individually, matching the TS reference behavior.
+
+## Test Results
+
+- **MetaObjects.Conformance.Tests**: Passed 680/680 (0 failed)
+  - registry-conformance: PASS (index.lookup registered with correct description/whenToUse/attrs; identity.secondary without @unique)
+  - metadata conformance index-lookup: PASS
+  - metadata conformance index-lookup-basic: PASS
+- **MetaObjects.Codegen.Tests**: Passed 265/265, Skipped 1 (expected)
+  - IndexLookupTests (6 tests): all PASS
+
+## EF codegen check
+
+Confirmed: no EF codegen code reads `identity.secondary` uniqueness. The only consumer of `MetaIdentity.Unique` was `MetaIdentity.cs` itself, and that property is removed. No EF model changes needed.
@@ -0,0 +1,63 @@
+# Task 9 Report: Kotlin Codegen (Exposed) — index.lookup + identity.secondary
+
+## Summary
+
+`KotlinExposedTableGenerator` now emits `index.lookup` children as non-unique Exposed indexes,
+and `identity.secondary` was already (correctly) always emitting `uniqueIndex(...)` — no
+`isUniqueKey()` call existed in the generator; Task 8 had already removed it from the metadata class
+before this task started.
+
+## Files Changed
+
+### `server/java/codegen-kotlin/src/main/kotlin/com/metaobjects/generator/kotlin/KotlinExposedTableGenerator.kt`
+
+1. **Added import**: `import com.metaobjects.index.LookupIndex`
+2. **Extended init-block emission** (lines ~483–502): The existing secondaries-only `init` block was
+   expanded to also iterate `entity.getChildren(LookupIndex::class.java, true)` (ADR-0039 resolving
+   accessor — `includeParentData=true` so inherited lookup indexes from abstract base entities are
+   visible). For each non-empty lookup index, emits `index("name", false, col1, col2, ...)`. The
+   combined `init` block is only emitted when at least one secondary or lookup index is present.
+   Views are excluded (same guard as secondaries: `if (isView) emptyList()`).
+
+### `server/java/codegen-kotlin/src/test/kotlin/com/metaobjects/generator/kotlin/KotlinExposedTableGeneratorTest.kt`
+
+Three new tests added in the `// === index.lookup coverage` section:
+
+- **`single index lookup emits non-unique Exposed index`**: single-field `index.lookup` → 
+  `index("idx_orders_status", false, status)` inside `init { }`.
+- **`composite index lookup emits multi-column non-unique index`**: two-field `index.lookup` →
+  `index("idx_events_tenant_type", false, tenantId, eventType)`.
+- **`entity with both identity secondary and index lookup shares one init block`**: mixed entity with
+  one `identity.secondary` and one `index.lookup` → exactly one `init { }` block containing both
+  `uniqueIndex(...)` and `index(..., false, ...)`.
+
+## Test Results
+
+```
+Tests run: 269, Failures: 0, Errors: 0, Skipped: 0  — BUILD SUCCESS
+KotlinExposedTableGeneratorTest: 37 tests (was 34 before, +3 new)
+```
+
+All 269 codegen-kotlin tests pass.
+
+## Golden / Snapshot Changes
+
+None. All assertions are behavioral (string containment in generated output), not snapshot files.
+
+## Implementation Notes
+
+- `identity.secondary` was already always emitting `uniqueIndex(...)` — no `isUniqueKey()` call
+  was present in the generator (Task 8 had already removed it from `SecondaryIdentity`). The
+  generator logic was correct; only the `index.lookup` fan-out was missing.
+- `@orders` (per-field sort direction on lookup indexes) is not emitted: the standard Exposed
+  `Table.index(name, isUnique, *columns)` API does not support per-column sort direction in the
+  version used by this project. The brief's "if the generator supports column ordering" clause
+  applies — Exposed does not, so it is deferred.
+- No named constants were needed beyond the already-imported Java constants (`LookupIndex`,
+  `Index.ATTR_FIELDS` is accessed via `idx.fields` which calls `getFields()` on the Java class
+  using the resolving accessor per ADR-0039).
+
+## Concerns
+
+None. The implementation is minimal, correct, and backward-compatible (entities without
+`index.lookup` children emit identical output to before).
@@ -430,6 +430,7 @@ Preserve the following contracts exactly across all language ports:
 - Source subtypes: `rdb` (paradigm; ADR-0007). The pre-v2 `dbTable`/`dbView` subtypes are RETIRED — `source.rdb` + `@kind: table|view|materializedView|storedProc|tableFunction` is the form, with read-only-ness derived from `@kind`. Multi-source via `@role` (exactly one `primary` per object). Source physical name = `@table` (NOT `@name`); field physical name = `@column` (renamed from `@dbColumn`). Referential actions on relationships: `@onDelete` / `@onUpdate`.
 - Origin subtypes: `passthrough`, `aggregate`
 - Relationship subtypes: `association`, `aggregation`, `composition`. Cardinality via `@cardinality: one|many`; target via `@objectRef`. **M:N (FR-018) slim vocabulary:** `@cardinality: "many"` + `@objectRef` (target) + `@through` (the junction/through entity — a third entity that MUST declare two `identity.reference` children, one per FK side). The relationship's FK fields are **derived** from those references (the `identity.reference` SSOT for FK direction), never restated. `@sourceRefField` (optional) disambiguates a *directed* self-join by naming the source-side FK field on the junction (the other reference is the target side). `@symmetric` (optional boolean) marks an *undirected* self-join (union-on-read) — valid only when `@objectRef` == the declaring entity, and mutually exclusive with `@sourceRefField`. The pre-FR-018 `@joinEntity`/`@joinFields` attrs are REMOVED. Validation errors: symmetric-on-hetero / symmetric+sourceRefField → `ERR_BAD_ATTR_VALUE`; junction-missing-two-references / sourceRefField-not-matching / M:N-attr-on-1:N → `ERR_INVALID_RELATIONSHIP`.
+- Index subtypes: `index.lookup` (non-unique retrieval index; uniqueness is encoded in the **type**: `identity.secondary` = unique alternate key, `index.lookup` = non-unique; `@unique` is REMOVED from `identity.secondary` — `ERR_UNKNOWN_ATTR` on any legacy `@unique`). RDB-physical escapes `@using`/`@expr`/`@where`/`@orders` are registered by the db provider on **both** `identity.secondary` and `index.lookup`. `index.fulltext` / `index.vector` / `index.spatial` are reserved on the subtype axis — documented, NOT registered (YAGNI + 1.0 vocab freeze). See [ADR-0040](spec/decisions/ADR-0040-index-type-and-secondary-key-purity.md).
 - Layout subtypes: `dataGrid`
 - API subtypes: `api.base` / `api.operational` (request/response surface; subtype axis = interaction model, NEVER protocol — protocol lives in `binding.*` per operation: `rest` now, `messaging`/`grpc` reserved). Children: `operation.query` (outputRef → `object.projection`) / `operation.command` (inputRef → `object.value`, may also outputRef). Derived CRUD (FR-008/009) stays the zero-config default; declared `api` extends it. Org-tier modeling (application/service/network/deployment) stays OUT of core — provider SPI, FQN references. See [ADR-0030](spec/decisions/ADR-0030-declared-api-surface-and-org-tier-boundary.md). (FR-024 declared-API — planned; not yet in `expected-registry.json`; the remaining third of FR-024 after the projection/value taxonomy + validation parity.)
 - Currency attrs: `@currency` (ISO 4217), `@locale` (BCP 47)
 
@@ -384,7 +384,7 @@ The `[]` key-suffix declares an array field: `field.long[]: weekIds` lowers to
 | Subtype | Purpose | Key attrs |
 |---|---|---|
 | `identity.primary` | the PK field(s) | `@fields`, `@generation` |
-| `identity.secondary` | a unique secondary index | `@fields` (or `@expr` for a functional index) |
+| `identity.secondary` | a unique alternate key (always enforces uniqueness — uniqueness is the type, not a `@unique` attr) | `@fields` (or `@expr` for a functional index) |
 | `identity.reference` | an inbound FK from this entity to another | `@fields`, `@references`, `@enforce` |
 
 `@generation` on a primary controls value generation (e.g. `increment`).
@@ -407,7 +407,7 @@ PK needs the explicit dotted form `@references: "pkg::Target.fieldA,fieldB"`.
 exist (previously such references loaded silently). So every `@references` /
 `@objectRef` you author must name a real entity.
 
-A `identity.secondary` can index an **expression** instead of plain columns: use
+An `identity.secondary` can index an **expression** instead of plain columns: use
 `@expr` (e.g. `"lower(email)"`) in place of `@fields`, optionally with `@using` (the
 index method — `gin` / `gist` / `hash`; default `btree`) and `@where` (a partial-index
 predicate).
@@ -419,6 +419,30 @@ predicate).
 { "identity.reference": { "name": "fkAuthor", "@fields": ["authorId"], "@references": "Author", "@enforce": true } }
 ```
 
+## Indexes (non-unique)
+
+Use `index.lookup` for a **non-unique** DB index added purely for query performance — it
+does NOT enforce uniqueness. Choose the right construct by what the constraint IS:
+
+| Need | Construct |
+|---|---|
+| Unique alternate key (e.g. email, slug) | `identity.secondary` — uniqueness is the type |
+| Query-performance index, no uniqueness | `index.lookup` |
+
+`@fields` names the indexed columns and is **required** (at least one). The db provider
+contributes physical-tuning attrs: `@orders` (per-column sort direction), `@using` (access
+method — `gin`/`gist`/`hash`; default `btree`), `@expr` (key expression derived from
+`@fields`, e.g. for a functional index), and `@where` (partial-index predicate).
+
+```json
+{ "index.lookup": { "name": "byCreatedAt", "@fields": ["createdAt"], "@orders": ["desc"] } }
+{ "index.lookup": { "name": "byStatusCreatedAt", "@fields": ["status", "createdAt"] } }
+{ "index.lookup": { "name": "byEmailCI", "@fields": ["email"], "@expr": "lower(email)" } }
+```
+
+`index.lookup` is a sibling of `identity.*` — declare it as a direct child of an `object.entity`,
+at the same level as fields and identities.
+
 ## Relationships
 
 `relationship.composition` is the "this entity owns / aggregates instances of
 
@@ -0,0 +1,187 @@
+# Migrating `identity.secondary @unique:false` → `index.lookup`
+
+`index.lookup` is the correct declaration for a **non-unique query-performance
+index**. The `@unique` attribute on `identity.secondary` was always wrong (the
+subtype is inherently unique — `@unique:false` was an unsupported override that
+had no effect on DDL) and is now rejected by the loader with
+`ERR_UNKNOWN_ATTR`.
+
+This guide explains the mechanical rewrite and confirms that the physical
+database schema is **unchanged** — no migration SQL is emitted.
+
+---
+
+## Rewrite rule
+
+### Non-unique index (the common case)
+
+`identity.secondary` with `@unique: false` (or any intent to produce a plain,
+non-unique index) → **replace with `index.lookup`** and drop the `@unique`
+attribute.
+
+**Before:**
+
+```json
+{
+  "identity.secondary": {
+    "name": "idx_orders_session",
+    "@fields": ["sessionId"],
+    "@unique": false
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "index.lookup": {
+    "name": "idx_orders_session",
+    "@fields": ["sessionId"]
+  }
+}
+```
+
+All physical index attributes (`@orders`, `@using`, `@where`, `@expr`) are
+supported on `index.lookup` and carry over unchanged.
+
+### Unique index (stays `identity.secondary`)
+
+`identity.secondary` with `@unique: true` or no `@unique` attribute → **keep
+`identity.secondary`** and drop the now-invalid `@unique` attribute (uniqueness
+is guaranteed by the subtype itself and never needs to be declared explicitly).
+
+**Before:**
+
+```json
+{
+  "identity.secondary": {
+    "name": "uq_users_email",
+    "@fields": ["email"],
+    "@unique": true
+  }
+}
+```
+
+**After:**
+
+```json
+{
+  "identity.secondary": {
+    "name": "uq_users_email",
+    "@fields": ["email"]
+  }
+}
+```
+
+---
+
+## Mechanical rewrite script
+
+The transformation is safe to apply automatically. The script below rewrites
+`.json` metadata files in place. Review the diff with `git diff` before
+committing.
+
+```bash
+#!/usr/bin/env bash
+# Rewrite non-unique identity.secondary → index.lookup in MetaObjects metadata
+# JSON files. Operates on all meta.*.json files under ./metaobjects/ (adjust
+# the glob for your layout).
+#
+# IMPORTANT: this is a line-oriented heuristic. Review the output with
+# `git diff` and run `meta verify` to confirm zero errors before committing.
+
+set -euo pipefail
+
+find metaobjects -name 'meta.*.json' -print0 | while IFS= read -r -d '' file; do
+  # Step 1: replace identity.secondary entries that contain "@unique": false
+  # with index.lookup (remove the @unique line).
+  # This uses Python for reliable multi-line JSON key surgery.
+  python3 - "$file" <<'PYEOF'
+import json, sys, re
+
+path = sys.argv[1]
+with open(path) as f:
+    text = f.read()
+
+data = json.loads(text)
+
+def transform(node):
+    if not isinstance(node, dict):
+        return node
+    result = {}
+    for key, val in node.items():
+        if key == "identity.secondary" and isinstance(val, dict):
+            unique = val.get("@unique")
+            # Non-unique intent: @unique explicitly false → rewrite to index.lookup
+            if unique is False:
+                new_val = {k: v for k, v in val.items() if k != "@unique"}
+                result["index.lookup"] = new_val
+            else:
+                # Unique (true or absent): keep as identity.secondary, drop @unique
+                new_val = {k: v for k, v in val.items() if k != "@unique"}
+                result["identity.secondary"] = new_val
+        elif isinstance(val, (dict, list)):
+            result[key] = transform(val)
+        else:
+            result[key] = val
+    return result
+
+def transform_list(node):
+    if isinstance(node, list):
+        return [transform_list(item) if isinstance(item, list)
+                else transform(item) if isinstance(item, dict)
+                else item
+                for item in node]
+    return transform(node)
+
+out = json.dumps(transform_list(data), indent=2)
+with open(path, "w") as f:
+    f.write(out + "\n")
+print(f"  rewrote: {path}")
+PYEOF
+done
+
+echo "Done. Run 'meta verify' to confirm zero loader errors."
+```
+
+---
+
+## No DDL churn — the physical schema is unchanged
+
+The physical index produced by `index.lookup` is byte-identical to the non-unique
+index that the old `identity.secondary @unique:false` would have produced. The
+`meta migrate` diff engine recognises this and emits **no migration SQL** — the
+`CREATE INDEX` statement already exists with the correct name, columns, and
+ordering.
+
+If you run `meta migrate` after the rewrite and see an unexpected `DROP INDEX` /
+`CREATE INDEX` pair, verify that:
+
+1. The index `name` is identical in both forms.
+2. The `@fields` list is unchanged (field names, not column names — the column
+   naming strategy is applied by the toolchain, not by the metadata author).
+3. Any `@orders`, `@using`, `@where`, or `@expr` values are carried over verbatim.
+
+---
+
+## Diagnosing the `ERR_UNKNOWN_ATTR` error
+
+If `meta verify` or `meta gen` reports:
+
+```
+ERR_UNKNOWN_ATTR: "@unique" is not a registered attribute for "identity.secondary"
+```
+
+a metadata file still contains `@unique` on an `identity.secondary` node. The
+rewrite script above eliminates all occurrences; if the error persists after
+running it, grep for any remaining occurrences:
+
+```bash
+grep -r '"@unique"' metaobjects/
+```
+
+Each hit is a remaining `@unique` that must be either removed (for
+`identity.secondary`, where uniqueness is the subtype default) or relocated to an
+`index.lookup` node (which does not accept `@unique` either — non-uniqueness is
+its subtype default).