test(persistence-conformance): 1:N self-referential FK roundtrip across all ports (#54)

Closes a real cross-port coverage gap: the only self-references in the shared corpus
were M:N junction self-joins (FR-018) — a plain 1:N self-FK (parentId → same entity)
was unexercised in every port. A 1:N self-FK is a scalar column (field.long) whose
FK-ness is declared by identity.reference; TS/Drizzle alone emits a column-level
.references() (the self-import bug fixed in #53), so the others are safe by construction
but were untested end-to-end.

Adds a `Node` entity (id PK + nullable parentId + identity.reference fkParent → Node) to
the persistence-conformance canonical metadata, regenerates the TS-owned schema SQL (now
emits the self-referencing FK constraint), and a `roundtrip-self-fk` scenario: a root
node (NULL parent) and a seeded-parent child, each written through the runtime/ORM write
codec and read back by PK. Per-port wiring: C# committed Node.g.cs + AppDbContext; Kotlin
hand-written NodeTable (PK-first so the self-reference resolves) + runner registration;
TS/Java/Python are metadata-driven (zero wiring). Updated the migration bootstrap's
expected table list to include `nodes`.

Verified: TS full integration (incl. the self-FK roundtrip) 111/0 against Testcontainers
PG; Kotlin + C# integration wiring compiles. Java/Python pick it up from the metadata.
Note: the codegen self-FK surface is already covered (TS via #53, Kotlin via an existing
pk-first codegen test, Java/C#/Python safe-by-construction) — this gates the runtime path.

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

Author: dmealing

fixtures/persistence-conformance/canonical/meta.fitness.json

@@ -28,6 +28,17 @@
           { "identity.reference": { "name": "fkProgram", "@fields": "programId", "@references": "Program" } }
         ]
       }},
+      { "object.entity": {
+        "name": "Node",
+        "children": [
+          { "source.rdb": { "@table": "nodes" } },
+          { "field.long":   { "name": "id" } },
+          { "field.string": { "name": "label", "@required": true, "@maxLength": 80 } },
+          { "field.long":   { "name": "parentId" } },
+          { "identity.primary":   { "name": "id", "@fields": "id", "@generation": "increment" } },
+          { "identity.reference": { "name": "fkParent", "@fields": "parentId", "@references": "Node" } }
+        ]
+      }},
       { "object.entity": {
         "name": "Measurement",
         "children": [

fixtures/persistence-conformance/canonical/schema.postgres.sql

@@ -23,6 +23,13 @@ CREATE TABLE "weeks" (
   CONSTRAINT "weeks_pkey" PRIMARY KEY ("id")
 );
 
+CREATE TABLE "nodes" (
+  "id" BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
+  "label" VARCHAR(80) NOT NULL,
+  "parentId" BIGINT,
+  CONSTRAINT "nodes_pkey" PRIMARY KEY ("id")
+);
+
 CREATE TABLE "measurements" (
   "id" BIGINT GENERATED BY DEFAULT AS IDENTITY NOT NULL,
   "tempC" REAL NOT NULL,
@@ -115,6 +122,8 @@ CREATE UNIQUE INDEX "byTitle" ON "programs" ("title");
 
 ALTER TABLE "weeks" ADD CONSTRAINT "weeks_programId_fk" FOREIGN KEY ("programId") REFERENCES "programs" ("id");
 
+ALTER TABLE "nodes" ADD CONSTRAINT "nodes_parentId_fk" FOREIGN KEY ("parentId") REFERENCES "nodes" ("id");
+
 ALTER TABLE "post_tags" ADD CONSTRAINT "post_tags_postId_fk" FOREIGN KEY ("postId") REFERENCES "posts" ("id");
 
 ALTER TABLE "post_tags" ADD CONSTRAINT "post_tags_tagId_fk" FOREIGN KEY ("tagId") REFERENCES "tags" ("id");

fixtures/persistence-conformance/migrations/bootstrap-canonical-from-empty.yaml

@@ -64,6 +64,7 @@ expect:
       - { table_name: "follows" }
       - { table_name: "friendships" }
       - { table_name: "measurements" }
+      - { table_name: "nodes" }
       - { table_name: "people" }
       - { table_name: "post_tags" }
       - { table_name: "posts" }

fixtures/persistence-conformance/queries/roundtrip-self-fk.yaml

@@ -0,0 +1,49 @@
+name: roundtrip-self-fk
+description: |
+  1:N self-referential FK write round-trip. Node has id (PK) + a NULLABLE
+  parentId → Node.id (declared via `identity.reference fkParent → Node`). Two
+  roundtrips: a root node (parentId omitted → NULL) and a child whose parentId
+  points at a seeded parent row. Each INSERTs through the port's runtime / ORM
+  write codec (NOT raw SQL), reads the row back by primary key, and asserts the
+  wire-normalized read-back (the PK is excluded from the comparison per the
+  op:roundtrip contract).
+
+  This is the ONLY 1:N self-referential FK in the corpus — every other self-
+  reference is an M:N junction self-join (FR-018 @symmetric / @sourceRefField).
+  A 1:N self-FK is realized as a plain scalar column (field.long) whose FK-ness
+  is declared by identity.reference; every port emits it as a scalar (TS/Drizzle
+  alone emits a column-level `.references()`, which is why only TS could hit a
+  self-import bug). The round-trip gates that the write codec handles a nullable
+  self-FK uniformly: NULL stays NULL, and a non-null value satisfies the self-
+  referencing FK constraint.
+
+  Wire rule: parentId is field.long → BIGINT → a numeric STRING on the wire
+  ("1000"); a NULL FK stays JSON null.
+
+# Seed a parent row so the child roundtrip's parentId references a real id.
+# id 1000 is well above the IDENTITY sequence start, so the runtime auto-id
+# inserts below it never collide (the column is GENERATED BY DEFAULT, so the
+# explicit seed value does not advance the sequence).
+seed-data: |
+  INSERT INTO "nodes" ("id", "label", "parentId") VALUES (1000, 'root', NULL);
+
+queries:
+  - name: write-root-node-null-parent
+    op: roundtrip
+    entity: Node
+    insert:
+      label: "another root"
+      # parentId omitted → NULL self-FK
+    expect:
+      label: "another root"
+      parentId: null
+
+  - name: write-child-node-with-parent
+    op: roundtrip
+    entity: Node
+    insert:
+      label: "child"
+      parentId: 1000
+    expect:
+      label: "child"
+      parentId: "1000"

server/csharp/MetaObjects.IntegrationTests/Generated/AppDbContext.g.cs

@@ -15,6 +15,7 @@ public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
     public DbSet<Follow> Follows { get; set; } = default!;
     public DbSet<Friendship> Friendships { get; set; } = default!;
     public DbSet<Measurement> Measurements { get; set; } = default!;
+    public DbSet<Node> Nodes { get; set; } = default!;
     public DbSet<Person> Persons { get; set; } = default!;
     public DbSet<Post> Posts { get; set; } = default!;
     public DbSet<PostTag> PostTags { get; set; } = default!;

server/csharp/MetaObjects.IntegrationTests/Generated/Node.g.cs

@@ -0,0 +1,23 @@
+// <auto-generated/>
+// Generated by MetaObjects entity-generator. Do not edit by hand.
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.ComponentModel.DataAnnotations;
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace MetaObjects.IntegrationTests.Generated;
+
+[Table("nodes")]
+public class Node
+{
+    [Key]
+    [Column("id")]
+    public long Id { get; set; }
+    [Column("label")]
+    [MaxLength(80)]
+    [Required]
+    public string Label { get; set; } = default!;
+    [Column("parentId")]
+    public long? ParentId { get; set; }
+}

server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/QueryScenarioRunner.kt

@@ -10,6 +10,7 @@ import com.metaobjects.integration.kotlin.Scenarios.QuerySpec
 import com.metaobjects.integration.kotlin.tables.AssetTable
 import com.metaobjects.integration.kotlin.tables.AuthTable
 import com.metaobjects.integration.kotlin.tables.MeasurementTable
+import com.metaobjects.integration.kotlin.tables.NodeTable
 import com.metaobjects.integration.kotlin.tables.ProgramStatView
 import com.metaobjects.integration.kotlin.tables.ProgramTable
 import com.metaobjects.integration.kotlin.tables.ProgramView
@@ -451,6 +452,7 @@ object QueryScenarioRunner {
     private fun tableFor(entity: String): Table = when (entity) {
         "Program" -> ProgramTable
         "Week" -> WeekTable
+        "Node" -> NodeTable
         "Measurement" -> MeasurementTable
         "ProgramStat" -> ProgramStatView
         "ProgramView" -> ProgramView

server/java/integration-tests-kotlin/src/test/kotlin/com/metaobjects/integration/kotlin/tables/NodeTable.kt

@@ -0,0 +1,21 @@
+package com.metaobjects.integration.kotlin.tables
+
+import org.jetbrains.exposed.sql.Table
+
+/**
+ * Hand-written reference Exposed Table mirroring `Node` from
+ * `fixtures/persistence-conformance/canonical/meta.fitness.json`.
+ *
+ * Self-referential NULLABLE FK: `parentId` references [id] on this SAME table,
+ * declared via `identity.reference fkParent → Node` on the canonical metadata.
+ * `id` is declared BEFORE `parentId` so the self-reference resolves during the
+ * object's top-to-bottom initialization (the same PK-first ordering the
+ * KotlinExposedTableGenerator emits for a generated self-FK table).
+ */
+object NodeTable : Table("nodes") {
+    val id = long("id").autoIncrement()
+    val label = varchar("label", 80)
+    val parentId = long("parentId").references(id).nullable()
+
+    override val primaryKey = PrimaryKey(id)
+}