fix(metadata): config-driven default name for singleton identities (FR-024 friction)

The no-name identity.primary form shown across the docs, llms-full, and the
website example FAILED to load (ERR_IDENTITY_NAME_REQUIRED) — a copy-paste trap
for users and agents. Fix it the config-driven way, gated by cardinality.

- New type-def config: `maxOccurs` (declared + loader-enforced) and `defaultName`.
  `defaultName` is honored ONLY when `maxOccurs === 1` — a static default name is
  collision-free by construction only for a singleton.
- spec/metamodel/identity.json: identity.primary -> { maxOccurs: 1, defaultName:
  "primary" }. A nameless primary now loads, named "primary" (stable + referenceable
  as Entity.primary). Multi-cardinality children (secondary/reference, validators,
  views) still require explicit names — no unpredictable counter auto-naming.
- TS reference: parser applies the default (singleton-gated); new validate-max-occurs
  pass enforces the singleton (catches two primaries); ERR_TOO_MANY_OCCURRENCES added.
  4 new tests; metadata suite green; the no-name CLI repro now generates.
- Cross-port: shared spec/metamodel + ERROR-CODES.json carry the change; Java (spec
  auto-copied) / Python / C# get the new error code + embedded spec. The DEFAULT-NAME
  behavior is TS-only for now, matching the existing FR-024 posture (Java/Python/C#
  don't enforce identity-name-required yet — so they never had the bug). All four
  ports verified green: TS 2035, Java 1046, C# conformance 657, Python conformance 301.

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

Author: dmealing

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 } }
           ]
         }
       }

server/csharp/MetaObjects/Errors.cs

@@ -19,6 +19,9 @@ public enum ErrorCode
     // Vocabulary-only here until FR-024 Phase E (the C# loader does not
     // enforce these yet); the enum tracks the shared corpus codes.
     ERR_IDENTITY_NAME_REQUIRED,
+    // A type.subType declared with maxOccurs (e.g. identity.primary, maxOccurs:1)
+    // appears more times than allowed under one parent.
+    ERR_TOO_MANY_OCCURRENCES,
     ERR_PROJECTION_IDENTITY_NOT_EXTENDED,
     ERR_IDENTITY_KEY_MISMATCH,
     // FR-024 (ADR-0028): a source.* on an object.projection has a writable

server/csharp/MetaObjects/SpecMetamodel/identity.json

@@ -5,6 +5,8 @@
       "type": "identity",
       "subType": "primary",
       "description": "The primary key — one per entity; @fields names its column(s), @generation the value strategy.",
+      "maxOccurs": 1,
+      "defaultName": "primary",
       "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": "string", "name": "generation", "min": 0, "max": 1, "allowedValues": ["increment", "uuid", "assigned"], "description": "Primary-key value generation strategy: 'increment' (auto-increment), 'uuid', or 'assigned' (caller-supplied)." }

server/java/metadata/src/main/java/com/metaobjects/ErrorCode.java

@@ -69,6 +69,14 @@ public enum ErrorCode {
      */
     ERR_IDENTITY_NAME_REQUIRED,
 
+    /**
+     * A {@code type.subType} declared with {@code maxOccurs} (e.g.
+     * identity.primary, maxOccurs:1) appears more times than allowed under one
+     * parent. The TS reference loader enforces it; other ports track the
+     * vocabulary until they apply the singleton constraint.
+     */
+    ERR_TOO_MANY_OCCURRENCES,
+
     /**
      * FR-024: an identity.* on an object.projection lacks extends — a
      * projection identity is a pass-through of an entity identity.

server/python/src/metaobjects/errors.py

@@ -23,6 +23,8 @@ class ErrorCode(str, Enum):
     # Vocabulary-only here until FR-024 Phase E (the Python loader does not
     # enforce these yet); the enum tracks the shared corpus codes.
     ERR_IDENTITY_NAME_REQUIRED = "ERR_IDENTITY_NAME_REQUIRED"
+    # A type.subType declared with maxOccurs (e.g. identity.primary) appears more than allowed under one parent.
+    ERR_TOO_MANY_OCCURRENCES = "ERR_TOO_MANY_OCCURRENCES"
     ERR_PROJECTION_IDENTITY_NOT_EXTENDED = "ERR_PROJECTION_IDENTITY_NOT_EXTENDED"
     ERR_IDENTITY_KEY_MISMATCH = "ERR_IDENTITY_KEY_MISMATCH"
     # FR-024 (ADR-0028): a source.* on an object.projection has a writable

server/python/src/metaobjects/spec_metamodel/identity.json

@@ -5,6 +5,8 @@
       "type": "identity",
       "subType": "primary",
       "description": "The primary key — one per entity; @fields names its column(s), @generation the value strategy.",
+      "maxOccurs": 1,
+      "defaultName": "primary",
       "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": "string", "name": "generation", "min": 0, "max": 1, "allowedValues": ["increment", "uuid", "assigned"], "description": "Primary-key value generation strategy: 'increment' (auto-increment), 'uuid', or 'assigned' (caller-supplied)." }

server/typescript/packages/metadata/src/core/identity/identity-definition.embedded.ts

@@ -13,6 +13,8 @@ export const IDENTITY_DEFINITION: ProviderDefinition = {
       "type": "identity",
       "subType": "primary",
       "description": "The primary key — one per entity; @fields names its column(s), @generation the value strategy.",
+      "maxOccurs": 1,
+      "defaultName": "primary",
       "children": [
         {
           "type": "attr",