feat(metamodel): value objects may carry navigation-only references (ADR-0046, #238)

dmealing · claude · dmealing · commit 78fbf90ed8eb · 2026-07-25T19:35:26.000-04:00
A non-persisted shape (API DTO, event payload, wire-protocol message) can now declare that a field references an entity, via the chartered navigation-only reference form: an `object.value` may carry an `identity.reference` with explicit `@enforce: false`. The loader resolves the `@references` target (dangling → ERR_INVALID_REFERENCE) and codegen emits no FK/DDL; a value's own identity (primary/secondary) and any enforced reference stay banned (ERR_SUBTYPE_RULE_VIOLATION). Zero new registry vocabulary — a child-licensing relaxation (ADR-0037 step 0), so registry-conformance is unaffected and existing `meta gen` output is byte-identical. Also closes the M:N junction guard this unmasks: value purity used to implicitly guarantee a `@through` junction was an entity (a value couldn't hold references); the `@through` validation now explicitly requires the junction resolve to an object.entity (ERR_INVALID_RELATIONSHIP otherwise) — a junction is a physical join table. Cross-port loader change (TS/Java/Python/C#; Kotlin inherits the JVM loader), gated by four new shared conformance fixtures. All four ports green on the metamodel conformance corpus (TS 498, Java 498, C# 816, Python 253). Surfaced by a reference-impl consumer modeling a wire protocol as MetaObjects. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014xy8powhHYJ6gfFt9Ut8dL
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -27,6 +27,37 @@ directional prompt-construction data-flow diagram (npm-only; `docs-site` + `cli`
 Additive: markdown surfaces and non-pipeline site output are unchanged. Gated by the
 `docs-site` golden (its AI fixture now exercises the full pipeline) + a link-graph unit test.
 
+### Added — value objects may carry navigation-only references (ADR-0046, #238)
+
+A non-persisted shape — an API DTO, an event payload, a wire-protocol command message —
+can now declare that a field references an entity, using the chartered navigation-only
+reference form. Previously value purity (ADR-0028) banned **all** identity/reference
+constructs on `object.value`, so a message carrying `tableId` had no way to say it
+references `Table`.
+
+- An `object.value` may now carry an `identity.reference` child **when it declares
+  explicit `@enforce: false`** (the already-chartered logical-reference form). The loader
+  resolves its `@references` target exactly as on an entity — a dangling target fails the
+  load with `ERR_INVALID_REFERENCE` — and codegen emits **no** FK/DDL (a value has no
+  table). A value's own identity (`identity.primary`/`identity.secondary`) and any
+  enforced reference stay banned (`ERR_SUBTYPE_RULE_VIOLATION`).
+- **Zero new vocabulary** — a child-licensing relaxation (ADR-0037 step 0), not an
+  expansion; `registry-conformance` is unaffected. The value↔entity dichotomy just gained
+  the "referencing DTO" it lacked without a new subtype.
+- **M:N junction guard made explicit.** Value purity used to *implicitly* guarantee that an
+  M:N `@through` junction was an `object.entity` (a value couldn't hold the two required
+  `identity.reference` children). Allowing navigation-only references on values removes that
+  implicit guard, so the `@through` validation now explicitly requires the junction resolve
+  to an `object.entity` (`ERR_INVALID_RELATIONSHIP` otherwise) — a junction is a physical
+  join table.
+
+Additive: no existing metadata triggers the relaxed rule, so `meta gen` output is
+byte-identical. This is a **cross-port loader change** (TS / Java / Python / C#; Kotlin
+inherits the JVM loader), gated by four new shared conformance fixtures
+(`value-reference-navigation-only` loads + resolves; `error-value-reference-enforced`,
+`error-value-reference-unresolved`, and `error-m2m-through-value` fail). See
+[ADR-0046](spec/decisions/ADR-0046-value-navigation-only-references.md).
+
 ## [0.20.2] — 2026-07-25
 
 **npm `0.20.2` only** (NuGet `0.19.3` / PyPI `0.19.5` / Maven Central `7.11.3` unchanged — no changed product file; D1 is a TS-only dialect). A bug-fix patch, no API or vocabulary change.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -30,7 +30,7 @@ _Last refreshed 2026-07-25._
 - **Kotlin** — `codegen-kotlin` (KotlinPoet on JVM): entity + Exposed table + Spring controller + payload + relations + filter allowlist + validator + stored-proc + output-parser generators. `integration-tests-kotlin` runs the persistence-conformance corpus through Exposed against Testcontainers Postgres.
 
 **Cross-port conformance corpora** (every port runs the shared corpus):
-- Metamodel: `fixtures/conformance/` (249 fixtures; 19 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
+- Metamodel: `fixtures/conformance/` (253 fixtures; 19 shared corpora in total — per-corpus counts + the corpus x port matrix live in `docs/CONFORMANCE.md`). TS / C# / Java / Python all green.
 - Render: `fixtures/render-conformance/`. TS / C# / Java / Kotlin / Python byte-identical.
 - Persistence: `fixtures/persistence-conformance/`. **Query** scenarios run on every port (TS / C# / Java / Kotlin / Python), each provisioning its test DB by executing the committed, TS-produced `canonical/schema.postgres.sql` (Postgres only — Derby dropped for the cross-port query corpus, ADR-0015). The **migration** scenarios are exercised by **TS only** (TS owns schema migrations). **The corpus now gates WRITES, not just reads (SP-H):** an `op: roundtrip` scenario type INSERTs through each port's runtime/ORM write codec (NOT raw SQL), reads the row back, and asserts the wire-normalized value. The `AllTypes` entity (`roundtrip-all-types.yaml`) carries one field of **every** persistable `field.*` subtype — string/int/long/double/float/decimal/boolean/date/time/timestamp(+tz)/currency/enum/uuid/object — plus an **array-of-VO** `field.object @isArray @storage:jsonb` column (`labels`, written as 2-element / empty-`[]` / single-element arrays across the three rows) — so every subtype write+read (incl. the array-of-value-object jsonb codec) round-trips through every port against Testcontainers PG. (`field.byte`/`field.short`/`field.class` were cut as non-functional registration-only stubs — the matrix tracks only genuinely-supported subtypes; see `fixtures/registry-conformance/README.md` → "Per-subtype write-round-trip matrix".)
 - API-contract: `fixtures/api-contract-conformance/`. TS / C# / Java / Kotlin / Python all green — each port runs **two lanes**: a hand-rolled reference server AND its **generated** API artifact booted over HTTP (the deployed controller/routes; TS+C# full-stack vs Testcontainers PG, Java/Kotlin/Python generated controller + in-memory repo behind the consumer seam). The generated fan-out found 10 real deployment bugs golden snapshots missed.
diff --git a/docs/CONFORMANCE.md b/docs/CONFORMANCE.md
@@ -25,7 +25,7 @@ regenerate with `ls -d fixtures/<corpus>/*/ | wc -l`.
 
 | Corpus | Fixtures | TS | Java | Kotlin | C# | Python |
 |---|---|---|---|---|---|---|
-| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 249 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
+| [`fixtures/conformance/`](../fixtures/conformance/) (metamodel) | 253 | ✓ | ✓ | inherits via `metadata-ktx` | ✓ | ✓ |
 | [`fixtures/yaml-conformance/`](../fixtures/yaml-conformance/) | 15 | 15 / 15 | 14 / 15 (1 ledgered: `yaml-quoted-leading-zero` — Java pipeline strips quotes off `"007"`) | inherits via Java | 14 / 15 (1 ledgered: `error-yaml-coerced-hex-in-string` — YamlDotNet doesn't coerce `0xFF`) | 15 / 15 |
 | [`fixtures/verify-conformance/`](../fixtures/verify-conformance/) | 31 | ✓ | ✓ | inherits via Java | ✓ | ✓ |
 | [`fixtures/verify-strict-conformance/`](../fixtures/verify-strict-conformance/) | 1 | ✓ | — | — | — | ✓ |
@@ -69,7 +69,7 @@ unit-test runners (`bun test`, `dotnet test`, `pytest`, `mvn test`) pull Docker.
 
 ## Fixture-to-doc mapping
 
-### `fixtures/conformance/` — metamodel loader + canonical serializer (249)
+### `fixtures/conformance/` — metamodel loader + canonical serializer (253)
 
 | Fixture prefix | Feature doc |
 |---|---|
@@ -139,7 +139,7 @@ the port's own GENERATED API artifact booted over HTTP.
 
 ## Orphaned fixtures (tested but not yet documented)
 
-The fixtures in the six corpora mapped above (metamodel 249 + yaml 15 + verify 31
+The fixtures in the six corpora mapped above (metamodel 253 + yaml 15 + verify 31
 + render 15 + persistence 30 + api-contract 41) each map to a feature doc. None
 are orphaned today. The remaining corpora in the totals table gate tooling
 contracts (registry manifests, provider composition, agent context, docs emit)
diff --git a/fixtures/conformance/error-m2m-through-value/expected-errors.json b/fixtures/conformance/error-m2m-through-value/expected-errors.json
@@ -0,0 +1,15 @@
+{
+  "errors": [
+    {
+      "code": "ERR_INVALID_RELATIONSHIP",
+      "source": {
+        "format": "json",
+        "files": [
+          "meta.commerce.json"
+        ],
+        "jsonPath": "$['metadata.root'].children[0]['object.entity'].children[1]['relationship.association']"
+      }
+    }
+  ],
+  "warnings": []
+}
diff --git a/fixtures/conformance/error-m2m-through-value/input/meta.commerce.json b/fixtures/conformance/error-m2m-through-value/input/meta.commerce.json
@@ -0,0 +1,44 @@
+{
+  "metadata.root": {
+    "package": "acme::commerce",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Post",
+          "children": [
+            { "field.long": { "name": "id" } },
+            {
+              "relationship.association": {
+                "name": "tags",
+                "@cardinality": "many",
+                "@objectRef": "acme::commerce::Tag",
+                "@through": "PostTag"
+              }
+            },
+            { "identity.primary": { "name": "id", "@fields": "id" } }
+          ]
+        }
+      },
+      {
+        "object.entity": {
+          "name": "Tag",
+          "children": [
+            { "field.long": { "name": "id" } },
+            { "identity.primary": { "name": "id", "@fields": "id" } }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "PostTag",
+          "children": [
+            { "field.long": { "name": "postId" } },
+            { "field.long": { "name": "tagId" } },
+            { "identity.reference": { "name": "postRef", "@fields": "postId", "@references": "acme::commerce::Post", "@enforce": false } },
+            { "identity.reference": { "name": "tagRef", "@fields": "tagId", "@references": "acme::commerce::Tag", "@enforce": false } }
+          ]
+        }
+      }
+    ]
+  }
+}
diff --git a/fixtures/conformance/error-value-reference-enforced/expected-errors.json b/fixtures/conformance/error-value-reference-enforced/expected-errors.json
@@ -0,0 +1,15 @@
+{
+  "errors": [
+    {
+      "code": "ERR_SUBTYPE_RULE_VIOLATION",
+      "source": {
+        "format": "json",
+        "files": [
+          "meta.poker.json"
+        ],
+        "jsonPath": "$['metadata.root'].children[1]['object.value'].children[1]['identity.reference']"
+      }
+    }
+  ],
+  "warnings": []
+}
diff --git a/fixtures/conformance/error-value-reference-enforced/input/meta.poker.json b/fixtures/conformance/error-value-reference-enforced/input/meta.poker.json
@@ -0,0 +1,32 @@
+{
+  "metadata.root": {
+    "package": "gaming::poker",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Table",
+          "children": [
+            { "field.uuid": { "name": "id" } },
+            { "field.string": { "name": "label" } },
+            { "identity.primary": { "name": "id", "@fields": ["id"] } }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "AskForStake",
+          "children": [
+            { "field.uuid": { "name": "tableId" } },
+            {
+              "identity.reference": {
+                "name": "tableRef",
+                "@fields": ["tableId"],
+                "@references": "Table"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
diff --git a/fixtures/conformance/error-value-reference-unresolved/expected-errors.json b/fixtures/conformance/error-value-reference-unresolved/expected-errors.json
@@ -0,0 +1,15 @@
+{
+  "errors": [
+    {
+      "code": "ERR_INVALID_REFERENCE",
+      "source": {
+        "format": "json",
+        "files": [
+          "meta.poker.json"
+        ],
+        "jsonPath": "$['metadata.root'].children[0]['object.value'].children[1]['identity.reference']"
+      }
+    }
+  ],
+  "warnings": []
+}
diff --git a/fixtures/conformance/error-value-reference-unresolved/input/meta.poker.json b/fixtures/conformance/error-value-reference-unresolved/input/meta.poker.json
@@ -0,0 +1,23 @@
+{
+  "metadata.root": {
+    "package": "gaming::poker",
+    "children": [
+      {
+        "object.value": {
+          "name": "AskForStake",
+          "children": [
+            { "field.uuid": { "name": "tableId" } },
+            {
+              "identity.reference": {
+                "name": "tableRef",
+                "@fields": ["tableId"],
+                "@references": "NoSuchTable",
+                "@enforce": false
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
diff --git a/fixtures/conformance/value-reference-navigation-only/expected.json b/fixtures/conformance/value-reference-navigation-only/expected.json
@@ -0,0 +1,59 @@
+{
+  "metadata.root": {
+    "package": "gaming::poker",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Table",
+          "children": [
+            {
+              "field.uuid": {
+                "name": "id"
+              }
+            },
+            {
+              "field.string": {
+                "name": "label"
+              }
+            },
+            {
+              "identity.primary": {
+                "name": "id",
+                "@fields": [
+                  "id"
+                ]
+              }
+            }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "AskForStake",
+          "children": [
+            {
+              "field.uuid": {
+                "name": "tableId"
+              }
+            },
+            {
+              "field.long": {
+                "name": "amount"
+              }
+            },
+            {
+              "identity.reference": {
+                "name": "tableRef",
+                "@enforce": false,
+                "@fields": [
+                  "tableId"
+                ],
+                "@references": "Table"
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
diff --git a/fixtures/conformance/value-reference-navigation-only/input/meta.poker.json b/fixtures/conformance/value-reference-navigation-only/input/meta.poker.json
@@ -0,0 +1,34 @@
+{
+  "metadata.root": {
+    "package": "gaming::poker",
+    "children": [
+      {
+        "object.entity": {
+          "name": "Table",
+          "children": [
+            { "field.uuid": { "name": "id" } },
+            { "field.string": { "name": "label" } },
+            { "identity.primary": { "name": "id", "@fields": ["id"] } }
+          ]
+        }
+      },
+      {
+        "object.value": {
+          "name": "AskForStake",
+          "children": [
+            { "field.uuid": { "name": "tableId" } },
+            { "field.long": { "name": "amount" } },
+            {
+              "identity.reference": {
+                "name": "tableRef",
+                "@fields": ["tableId"],
+                "@references": "Table",
+                "@enforce": false
+              }
+            }
+          ]
+        }
+      }
+    ]
+  }
+}
diff --git a/server/csharp/MetaObjects/Loader/ValidationPasses.cs b/server/csharp/MetaObjects/Loader/ValidationPasses.cs
@@ -114,14 +114,32 @@ private static void WalkSubtypeRules(
         }
     }
 
-    // FR-024 value purity (ADR-0028): a value object is a pure data shape — it
-    // carries NO identity of any subtype and NO source.
+    // FR-024 value purity (ADR-0028): a value object owns NO identity and NO source.
+    // ADR-0046 admits ONE exception: a navigation-only identity.reference with explicit
+    // @enforce:false — an outbound pointer to an entity (a DTO/message referencing X by
+    // id) is not persistence. Its target still resolves (dangling → ERR_INVALID_REFERENCE
+    // via the registry-derived pass) and codegen emits no FK/DDL. The value's OWN identity
+    // (primary/secondary) and any enforced reference (a physical FK it has no table to
+    // hold) stay banned.
     private static void ValidateValuePurity(MetaData model, List<MetaError> errors)
     {
         foreach (var child in model.Children())
         {
             if (child.Type == TYPE_IDENTITY)
             {
+                if (child.SubType == IDENTITY_SUBTYPE_REFERENCE)
+                {
+                    // ADR-0046: navigation-only reference is the sanctioned exception.
+                    if (child.Attr(IDENTITY_REFERENCE_ATTR_ENFORCE) is false) continue;
+                    errors.Add(new MetaError(
+                        $"value object '{model.Fqn()}' has an enforced reference " +
+                        $"({TYPE_IDENTITY}.{child.SubType} '{child.Name}') — a value is not persisted " +
+                        "and has no table to hold a physical FK; declare a navigation-only reference " +
+                        "with @enforce: false (FR-024, ADR-0028, ADR-0046)",
+                        ErrorCode.ERR_SUBTYPE_RULE_VIOLATION,
+                        Envelope: child.Source));
+                    continue;
+                }
                 errors.Add(new MetaError(
                     $"value object '{model.Fqn()}' must not have an identity " +
                     $"({TYPE_IDENTITY}.{child.SubType} '{child.Name}') — value objects are " +
@@ -2765,6 +2783,20 @@ public static IReadOnlyList<MetaError> ValidateRelationships(MetaData root)
                         Envelope: ResolvedSource.From(rel.Source, $"{obj.Fqn()}::{rel.Name}", (string)through!)));
                     continue;
                 }
+                // A junction is a physical join table — it MUST be an object.entity. ADR-0046
+                // lets a value carry navigation-only references, so value-purity no longer
+                // implicitly guarantees a two-reference junction is an entity; assert it here.
+                // (A value/projection has no table to join through.)
+                if (junction.SubType != OBJECT_SUBTYPE_ENTITY)
+                {
+                    errors.Add(new MetaError(
+                        $"relationship \"{obj.Name}.{rel.Name}\" @{RELATIONSHIP_ATTR_THROUGH} \"{through}\" resolves to " +
+                        $"{junction.Type}.{junction.SubType}, not an entity — a junction is a persisted join table " +
+                        "and must be object.entity.",
+                        ErrorCode.ERR_INVALID_RELATIONSHIP,
+                        Envelope: rel.Source));
+                    continue;
+                }
                 int refCount = CountJunctionReferences(junction);
                 if (refCount != 2)
                 {
diff --git a/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java b/server/java/metadata/src/main/java/com/metaobjects/loader/ValidationPhase.java
diff --git a/server/python/src/metaobjects/loader/validation_passes.py b/server/python/src/metaobjects/loader/validation_passes.py
diff --git a/server/typescript/packages/metadata/src/loader/validation-passes.ts b/server/typescript/packages/metadata/src/loader/validation-passes.ts
diff --git a/server/typescript/packages/metadata/src/subtype-rules.ts b/server/typescript/packages/metadata/src/subtype-rules.ts
diff --git a/server/typescript/packages/metadata/test/subtype-rules.test.ts b/server/typescript/packages/metadata/test/subtype-rules.test.ts
diff --git a/spec/decisions/ADR-0046-value-navigation-only-references.md b/spec/decisions/ADR-0046-value-navigation-only-references.md
