fix(metadata): config-driven default name for singleton identities (#44)

Config-driven `maxOccurs`/`defaultName` on the type registration so a name-less singleton `identity.primary` loads as `"primary"` (referenceable as `Entity.primary`), while multi-cardinality children still require explicit names. New `ERR_TOO_MANY_OCCURRENCES` on two primaries. Cross-port spec (`spec/metamodel/identity.json`); default-name enforcement TS-side per the existing FR-024 posture.

Admin-merged: all substantive checks green on the head commit; the pull_request-only gates (release-gate/migrate-ts-pg/leak-scan) passed on the prior SHA and the only delta since was a non-null-assertion in one TS test file.

Author: dmealing

docs/features/entities.md

@@ -76,6 +76,13 @@ YAML is desugared to canonical JSON at load time. See
 | `identity.secondary` | Unique secondary index. | No. |
 | `identity.reference` | Inbound FK from this entity to another. | No. |
 
+> **`identity.primary` is a singleton — its name is optional.** An entity may carry
+> at most one `identity.primary`; the loader names a name-less one `"primary"`
+> automatically (so `{ "identity.primary": { "@fields": "id" } }` is the canonical
+> minimal form — no need to invent a name). Declaring two primaries on one entity is
+> an `ERR_TOO_MANY_OCCURRENCES` load error. `identity.secondary` / `identity.reference`
+> are not singletons and DO require an explicit `name`.
+
 ## `extends:` for shared abstract bases
 
 Common base fields (`id`, `createdAt`, `updatedAt`) live on an abstract entity that

docs/superpowers/specs/2026-06-18-identity-default-name-design.md

@@ -0,0 +1,81 @@
+# Config-driven default name for singleton child types (fix the load-breaking identity bug)
+
+> Status: design (agreed). Written 2026-06-18. Fixes a real, widespread load-breaking bug:
+> `identity.primary` requires an author-chosen `name` (FR-024), but the no-name form is what
+> ~8 doc files, `docs/llms/llms-full.txt` (the LLM context), the metaobjects.dev homepage
+> example, and most quickstarts show — so a user *or Claude* who copy-pastes the canonical
+> example gets a model that **fails to load** (`ERR_IDENTITY_NAME_REQUIRED`).
+
+## Problem (verified)
+
+`server/typescript/packages/metadata/src/subtype-rules.ts` (FR-024 D2) errors when any
+`identity.*` node has `name === ""`. The docs/website/llms-full teach exactly that form.
+Reproduced: a minimal model with `identity.primary: { fields: id }` (no name) fails to load.
+
+## Decision
+
+Make the default **config-driven**, and only where it is unambiguous:
+
+1. **Default-name applies only to singleton child types** — a type that can occur *at most
+   once per parent*. A static default name is collision-free **by construction** only for a
+   singleton; for multi-cardinality children (validators, views, secondary/reference
+   identities) a static default would collide.
+2. **Cardinality is declared AND enforced in the provider JSON config.** Add a type-level
+   `maxOccurs` to the type definition (`spec/metamodel/*.json` → `TypeDef`). The loader
+   enforces it (error on more than `maxOccurs` of that `type.subType` under one parent).
+3. **`defaultName` is honored only when `maxOccurs === 1`.** Add a type-level `defaultName`
+   to the config; the loader assigns it when the node's name is empty.
+4. **No counter-append auto-naming.** The historical "append a number per new validator/view"
+   trick is rejected here: it produces *unpredictable* names that are hard to reference later
+   and would confuse an LLM trying to `extends`/address a node — which cuts against the
+   "LLM authors the model" thesis. Multi-cardinality children stay explicitly named.
+
+`identity.primary` is the motivating case: exactly one per entity → `maxOccurs: 1`,
+`defaultName: "primary"`. Stable and referenceable as `Entity.primary`.
+
+## Changes
+
+### Config (canonical source + embedded)
+- `spec/metamodel/identity.json`: on `identity.primary`, add `"maxOccurs": 1`,
+  `"defaultName": "primary"`. Regenerate the embedded definitions
+  (`bun run scripts/generate-embedded-metamodel.ts`).
+- `provider-data.ts` `TypeDef`: add optional `maxOccurs?: number` and `defaultName?: string`.
+  Thread both into the registry's type-definition record.
+
+### Loader
+- During load, **before** the FR-024 name check, for any node with `name === ""`: look up its
+  `type.subType` definition; if `maxOccurs === 1` and `defaultName` is set, assign the name.
+- Add `maxOccurs` enforcement: count siblings of the same `type.subType` per parent; error
+  (`ERR_TOO_MANY_<TYPE>` / reuse an existing code) when the count exceeds `maxOccurs`.
+- `subtype-rules.ts` FR-024 D2: only error when the name is still empty after the default pass
+  (so `identity.secondary`/`reference` — no `defaultName` — still require explicit names).
+
+### Conformance
+- Add a `fixtures/conformance/` fixture: an entity whose `identity.primary` omits the name →
+  loads, and the effective/canonical serialization shows `name: "primary"`. Plus a negative
+  fixture: two `identity.primary` under one entity → `maxOccurs` error.
+- Add to `registry-conformance` if `maxOccurs`/`defaultName` surface in the manifest.
+
+### Cross-port parity
+The loader/subtype-rules exist per port (TS / Java / Python / C#). Ship TS as the reference,
+then mirror `maxOccurs` + `defaultName` honoring in Java/Python/C# so the conformance fixture
+passes on all five ports (the change is small and mechanical: read two config fields, apply +
+enforce). The default vocabulary (`identity.primary → "primary"`) is identical everywhere.
+
+### Sweep (separate, can land first)
+Regardless of the engine change, fix the broken examples to a loading form (add explicit
+`name:`): the ~8 feature docs, `docs/llms/llms-full.txt`, the `.claude` skills' examples, and
+both website canonical examples. After the loader-default ships, the no-name form *also*
+loads, but explicit-name docs stay correct and forward-compatible.
+
+## Non-goals
+- Counter-append auto-naming for validators/views (rejected — unpredictable, LLM-hostile).
+- A dynamic name-generation strategy DSL. (Could revisit a deterministic `<field>`-scoped
+  default for field-nested singletons later; out of scope here.)
+
+## Why this is the right call
+It removes the single most common bit of YAML bloat (every entity's primary identity) while
+keeping names **stable, predictable, and referenceable** — the property an LLM-authored model
+depends on. The cardinality gate makes the default safe by construction, and putting both
+`maxOccurs` and `defaultName` in the provider config keeps it declarative (ADR-0023), not a
+hardcoded loader special-case.

fixtures/conformance/ERROR-CODES.json

@@ -10,6 +10,7 @@
     "ERR_UNRESOLVED_SUPER": "An extends/super reference names a node that does not exist.",
     "ERR_EXTENDS_TARGET_MISMATCH": "FR-024: a dotted extends ref resolved to a node whose type or subtype does not match the extending node (a field may only extend a field of the same subtype; an identity only an identity).",
     "ERR_IDENTITY_NAME_REQUIRED": "FR-024: an identity.* node has no name. Identities are named, author-chosen (e.g. \"id\"), so the dotted by-name extends form can address them.",
+    "ERR_TOO_MANY_OCCURRENCES": "A type.subType declared with maxOccurs (e.g. identity.primary, maxOccurs:1) appears more times than allowed under one parent.",
     "ERR_PROJECTION_IDENTITY_NOT_EXTENDED": "FR-024: an identity.* on an object.projection lacks extends — a projection identity is a pass-through of an entity identity.",
     "ERR_IDENTITY_KEY_MISMATCH": "FR-024: identity key correspondence broken — an extended-identity field has no local pass-through field extending it, or an explicit @fields disagrees with the computed pass-through key.",
     "ERR_PROJECTION_SOURCE_WRITABLE": "FR-024 (ADR-0028): a source.* on an object.projection has a writable @kind (table, or @kind omitted which defaults to table) — a projection is a derived read-only representation; its sources must be read-only kinds (view, materializedView, storedProc, tableFunction).",

fixtures/conformance/error-identity-name-required/expected-errors.json

@@ -7,7 +7,7 @@
         "files": [
           "meta.demo.json"
         ],
-        "jsonPath": "$['metadata.root'].children[0]['object.entity'].children[1]['identity.primary']"
+        "jsonPath": "$['metadata.root'].children[0]['object.entity'].children[3]['identity.secondary']"
       }
     }
   ],

fixtures/conformance/error-identity-name-required/input/meta.demo.json

@@ -7,7 +7,9 @@
           "name": "Customer",
           "children": [
             { "field.uuid": { "name": "id" } },
-            { "identity.primary": { "@fields": ["id"] } }
+            { "field.string": { "name": "email" } },
+            { "identity.primary": { "name": "pk", "@fields": ["id"] } },
+            { "identity.secondary": { "@fields": ["email"], "@unique": true } }
           ]
         }
       }

fixtures/conformance/error-too-many-primary/expected-errors.json

@@ -0,0 +1,13 @@
+{
+  "errors": [
+    {
+      "code": "ERR_TOO_MANY_OCCURRENCES",
+      "source": {
+        "format": "json",
+        "files": ["meta.demo.json"],
+        "jsonPath": "$['metadata.root'].children[0]['object.entity'].children[3]['identity.primary']"
+      }
+    }
+  ],
+  "warnings": []
+}

fixtures/conformance/error-too-many-primary/input/meta.demo.json

@@ -0,0 +1,18 @@
+{
+  "metadata.root": {
+    "package": "demo",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Customer",
+          "children": [
+            { "field.long": { "name": "id" } },
+            { "field.long": { "name": "altId" } },
+            { "identity.primary": { "name": "pk", "@fields": ["id"] } },
+            { "identity.primary": { "name": "pk2", "@fields": ["altId"] } }
+          ]
+        }
+      }
+    ]
+  }
+}

fixtures/conformance/error-too-many-primary/providers.json

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

fixtures/conformance/identity-primary-default-name/expected-effective.json

@@ -0,0 +1,34 @@
+{
+  "metadata.root": {
+    "package": "demo",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Customer",
+          "children": [
+            {
+              "source.rdb": {
+                "@table": "customers"
+              }
+            },
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "identity.primary": {
+                "name": "primary",
+                "@fields": [
+                  "id"
+                ],
+                "@generation": "increment"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+

fixtures/conformance/identity-primary-default-name/expected.json

@@ -0,0 +1,34 @@
+{
+  "metadata.root": {
+    "package": "demo",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Customer",
+          "children": [
+            {
+              "source.rdb": {
+                "@table": "customers"
+              }
+            },
+            {
+              "field.long": {
+                "name": "id"
+              }
+            },
+            {
+              "identity.primary": {
+                "name": "primary",
+                "@fields": [
+                  "id"
+                ],
+                "@generation": "increment"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
+