docs: scrub retired @referencedBy + value*/data* references from unused fixtures + migration docs (SP-G Java recon)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dmealing

server/java/MIGRATION.md

@@ -5,7 +5,7 @@
 7.1.0 is a cleanup release with three **breaking** packaging changes for consumers already on 7.0.0, plus additive features (full list in [RELEASE_NOTES.md](RELEASE_NOTES.md#version-710-2026-05-28)).
 
 1. **OSGi runtime variant removed.** If you consumed the OSGi bundles or called the OSGi-specific `ServiceRegistry` methods, see [OSGi support removed](#osgi-support-removed) below for the exact API delta and the `bnd` / `pax-url` wrap path.
-2. **`metaobjects-dynamic-core` folded into `metaobjects-metadata`.** Drop any `com.metaobjects:metaobjects-dynamic-core` dependency — its `CoreObjectsMetaDataProvider` (and the `dataBuilderClass` / `valueObjectType` attribute extensions on `object.base`) now ship inside `metaobjects-metadata`. No change for consumers of those attribute names.
+2. **`metaobjects-dynamic-core` folded into `metaobjects-metadata`.** Drop any `com.metaobjects:metaobjects-dynamic-core` dependency — its `CoreObjectsMetaDataProvider` now ships inside `metaobjects-metadata`. The `value*` / `data*` attribute extensions it used to contribute onto `object.base` (e.g. `valueObjectType`, `dataBuilderClass`, `dataImmutable`) have been **removed** — generated-object flavor is now derived from the codegen generator's configuration, not from metamodel attributes. If you authored any of those attributes in metadata, delete them.
 3. **`archetype` / `examples` directories deleted.** No action unless you referenced them as source.
 
 Additive (opt-in) in 7.1.0: [programmatic provider registration](#programmatic-provider-registration-new-in-710), the `TemplateGenerator` render API in `metaobjects-render`, `codegen-spring` `hasFoo()` presence helpers for nullable record fields, and `codegen-kotlin` `text()` mapping for jsonb-backed string fields.
@@ -46,7 +46,7 @@ Five module additions in 7.0.0 (none required; opt in per stack):
 | `metaobjects-metadata-ktx` | Kotlin facade over the Java metadata core |
 | `metaobjects-omdb-ktx` | Kotlin facade over OMDB |
 
-The `metaobjects-dynamic-core` module from 6.x is gone — its `CoreObjectsMetaDataProvider` (which contributed `dataBuilderClass`, `valueObjectType`, etc., attribute extensions onto `object.base`) now ships inside `metaobjects-metadata`. Consumers of those attribute names need no change; consumers of the `metaobjects-dynamic-core` artifact coordinate should drop the dependency.
+The `metaobjects-dynamic-core` module from 6.x is gone — its `CoreObjectsMetaDataProvider` now ships inside `metaobjects-metadata`. The `value*` / `data*` attribute extensions it once contributed onto `object.base` (`dataBuilderClass`, `valueObjectType`, `dataImmutable`, etc.) have since been **removed**: generated-object flavor is derived from the codegen generator's configuration rather than from metamodel attributes, so there is nothing for consumers to register or author. Consumers of the `metaobjects-dynamic-core` artifact coordinate should drop the dependency; any of those attributes still present in authored metadata should be deleted.
 
 ### OSGi support removed
 

server/java/metadata/src/test/resources/relationship-examples/README.md

@@ -4,12 +4,29 @@ This directory contains example metadata JSON files demonstrating the MetaObject
 
 ## Core Relationship Patterns
 
-### Essential Attributes (AI specifies these 4)
+### Essential Attributes (AI specifies these)
 
 1. **`@objectRef`** - The target object this relationship points to
 2. **`@cardinality`** - Either "one" or "many"
 3. **`@ownership`** - Either "owns" or "references"
-4. **`@referencedBy`** - Field name that implements the relationship
+
+### FK direction is declared by `identity.reference`, not on the relationship
+
+A relationship no longer restates the implementing FK field. Foreign-key
+direction is the responsibility of an **`identity.reference`** child on the entity
+that physically holds the FK column:
+
+```json
+{ "identity.reference": { "name": "categoryRef", "@fields": "categoryId", "@references": "Category" } }
+```
+
+- **`@fields`** - the local FK field (or comma-separated fields for a composite key)
+- **`@references`** - the target entity the FK points at
+
+For a `@cardinality: "one"` relationship the FK lives on the declaring entity, so
+that entity carries the `identity.reference`. For `@cardinality: "many"` the FK
+lives on the child (one-to-many) or in a junction entity (many-to-many), so the
+`identity.reference` lives there. The relationship itself stays purely semantic.
 
 ### Derived Properties (automatic)
 
@@ -25,13 +42,16 @@ This directory contains example metadata JSON files demonstrating the MetaObject
     "name": "profile",
     "@objectRef": "UserProfile",
     "@cardinality": "one",
-    "@ownership": "owns",
-    "@referencedBy": "profileId"
+    "@ownership": "owns"
   }
 }
 ```
+FK is on the declaring (parent) entity:
+```json
+{ "identity.reference": { "name": "profileRef", "@fields": "profileId", "@references": "UserProfile" } }
+```
 **Meaning**: Parent object owns exactly one child object. When parent is deleted, child is also deleted.
-**RDB Implementation**: Foreign key in child table, cascade delete
+**RDB Implementation**: Foreign key on the parent row, cascade delete
 **Examples**: User → Profile, Order → PaymentInfo
 
 ### 2. One-to-Many Composition (owns + many)
@@ -41,11 +61,14 @@ This directory contains example metadata JSON files demonstrating the MetaObject
     "name": "addresses",
     "@objectRef": "Address",
     "@cardinality": "many",
-    "@ownership": "owns",
-    "@referencedBy": "addressIds"
+    "@ownership": "owns"
   }
 }
 ```
+FK is on the child entity (`Address`), declared there:
+```json
+{ "identity.reference": { "name": "userRef", "@fields": "userId", "@references": "User" } }
+```
 **Meaning**: Parent object owns multiple child objects. When parent is deleted, all children are deleted.
 **RDB Implementation**: Foreign key in child table, cascade delete
 **Examples**: User → Addresses, Order → OrderItems
@@ -57,13 +80,16 @@ This directory contains example metadata JSON files demonstrating the MetaObject
     "name": "manager",
     "@objectRef": "User",
     "@cardinality": "one",
-    "@ownership": "references",
-    "@referencedBy": "managerId"
+    "@ownership": "references"
   }
 }
 ```
+FK is on the declaring entity:
+```json
+{ "identity.reference": { "name": "managerRef", "@fields": "managerId", "@references": "User" } }
+```
 **Meaning**: Parent object references exactly one independent object. Lifecycle is independent.
-**RDB Implementation**: Foreign key in parent table, no cascade delete
+**RDB Implementation**: Foreign key on the declaring row, no cascade delete
 **Examples**: Employee → Manager, Order → Customer
 
 ### 4. One-to-Many Association (references + many)
@@ -73,13 +99,12 @@ This directory contains example metadata JSON files demonstrating the MetaObject
     "name": "favoriteProducts",
     "@objectRef": "Product",
     "@cardinality": "many",
-    "@ownership": "references",
-    "@referencedBy": "favoriteProductIds"
+    "@ownership": "references"
   }
 }
 ```
 **Meaning**: Parent object references multiple independent objects. Lifecycle is independent.
-**RDB Implementation**: Junction table or array of foreign keys
+**RDB Implementation**: Junction table; each FK side is declared as an `identity.reference` on the junction entity (see M:N vocabulary)
 **Examples**: User → FavoriteProducts, Category → Products
 
 ## Example Files
@@ -110,7 +135,9 @@ AI only needs to choose:
 1. **Target Object** - What object does this point to?
 2. **Cardinality** - One or many?
 3. **Ownership** - Does parent own the child or just reference it?
-4. **Field Name** - What field implements this relationship?
+
+The implementing FK is declared separately as an `identity.reference` on whichever
+entity physically holds the FK column.
 
 ### Cross-Language Mapping
 The semantic model maps directly to:
@@ -184,10 +211,13 @@ The relationship system replaces the database-specific MetaKey system:
     "name": "user",
     "@objectRef": "User",
     "@cardinality": "one",
-    "@ownership": "references",
-    "@referencedBy": "userId"
+    "@ownership": "references"
   }
 }
 ```
+with the FK direction declared on the entity that holds the column:
+```json
+{ "identity.reference": { "name": "userRef", "@fields": "userId", "@references": "User" } }
+```
 
 The relationship approach is more semantic and works across different persistence technologies (RDB, document stores, graph databases).

server/java/metadata/src/test/resources/relationship-examples/blog-relationships.json

@@ -41,19 +41,24 @@
                 "@maxLength": 100
               }
             },
+            {
+              "identity.reference": {
+                "name": "profileRef",
+                "@fields": "profileId",
+                "@references": "AuthorProfile"
+              }
+            },
             {
               "relationship.composition": {
                 "name": "posts",
                 "@cardinality": "many",
-                "@referencedBy": "postIds",
                 "@objectRef": "BlogPost"
               }
             },
             {
               "relationship.composition": {
                 "name": "profile",
                 "@cardinality": "one",
-                "@referencedBy": "profileId",
                 "@objectRef": "AuthorProfile"
               }
             }
@@ -167,27 +172,31 @@
                 "@required": true
               }
             },
+            {
+              "identity.reference": {
+                "name": "categoryRef",
+                "@fields": "categoryId",
+                "@references": "Category"
+              }
+            },
             {
               "relationship.composition": {
                 "name": "comments",
                 "@cardinality": "many",
-                "@referencedBy": "commentIds",
                 "@objectRef": "Comment"
               }
             },
             {
               "relationship.association": {
                 "name": "tags",
                 "@cardinality": "many",
-                "@referencedBy": "tagIds",
                 "@objectRef": "Tag"
               }
             },
             {
               "relationship.association": {
                 "name": "category",
                 "@cardinality": "one",
-                "@referencedBy": "categoryId",
                 "@objectRef": "Category"
               }
             }
@@ -247,19 +256,24 @@
                 "@column": "approved"
               }
             },
+            {
+              "identity.reference": {
+                "name": "parentCommentRef",
+                "@fields": "parentCommentId",
+                "@references": "Comment"
+              }
+            },
             {
               "relationship.association": {
                 "name": "parentComment",
                 "@cardinality": "one",
-                "@referencedBy": "parentCommentId",
                 "@objectRef": "Comment"
               }
             },
             {
               "relationship.association": {
                 "name": "replies",
                 "@cardinality": "many",
-                "@referencedBy": "replyIds",
                 "@objectRef": "Comment"
               }
             }
@@ -347,11 +361,17 @@
                 "@maxLength": 500
               }
             },
+            {
+              "identity.reference": {
+                "name": "parentCategoryRef",
+                "@fields": "parentCategoryId",
+                "@references": "Category"
+              }
+            },
             {
               "relationship.association": {
                 "name": "parentCategory",
                 "@cardinality": "one",
-                "@referencedBy": "parentCategoryId",
                 "@objectRef": "Category"
               }
             }