merge: C# table DDL — FK constraints + @storage object columns [FR-003]

dmealing · claude · dmealing · commit d14c226dee70 · 2026-05-23T15:40:18.000-04:00
CreateTable now emits FOREIGN KEY constraints (from enforced identity.reference)
and @storage object-field columns (flattened -&gt; prefixed columns; else jsonb),
mirroring the TS migrate expected-schema. Full C# solution green (277 tests).

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/server/csharp/MetaObjects.Codegen.Tests/PostgresSchemaTests.cs b/server/csharp/MetaObjects.Codegen.Tests/PostgresSchemaTests.cs
@@ -7,8 +7,10 @@ namespace MetaObjects.Codegen.Tests;
 
 public class PostgresSchemaTests
 {
-    // Week + Program (tables). Week.fkProgram is the FK (identity.reference) and
-    // Week.program is the to-one navigation back to Program.
+    // Week + Program + Tag (tables). Week.fkProgram is the FK (identity.reference)
+    // and Week.program is the to-one navigation back to Program; Tag.fkProgramLogical
+    // is a logical-only (@enforce: false) reference. Program.homeAddress is a
+    // @storage flattened object field; Program.config is a default (jsonb) object.
     //   ProgramView      — passthrough projection (plain columns).
     //   ProgramStat      — aggregate (count over Program.weeks -> correlated subquery).
     //   WeekDetail       — passthrough-@via (forwards Program.title via Week.program).
@@ -23,10 +25,23 @@ public class PostgresSchemaTests
         { "identity.reference": { "name": "fkProgram", "@fields": "programId", "@references": "Program" } },
         { "relationship.association": { "name": "program", "@objectRef": "Program", "@cardinality": "one" } }
       ]}},
+      { "object.entity": { "name": "Tag", "children": [
+        { "source.dbTable": { "@name": "tags" } },
+        { "field.long": { "name": "id" } },
+        { "field.long": { "name": "programId" } },
+        { "identity.primary": { "@fields": "id" } },
+        { "identity.reference": { "name": "fkProgramLogical", "@fields": "programId", "@references": "Program", "@enforce": false } }
+      ]}},
+      { "object.value": { "name": "Address", "children": [
+        { "field.string": { "name": "street", "@required": true, "@maxLength": 120 } },
+        { "field.string": { "name": "city", "@maxLength": 80 } }
+      ]}},
       { "object.entity": { "name": "Program", "children": [
         { "source.dbTable": { "@name": "programs" } },
         { "field.long":   { "name": "id" } },
         { "field.string": { "name": "title", "@required": true, "@maxLength": 200 } },
+        { "field.object": { "name": "homeAddress", "@objectRef": "Address", "@storage": "flattened" } },
+        { "field.object": { "name": "config", "@objectRef": "Address" } },
         { "relationship.aggregation": { "name": "weeks", "@objectRef": "Week", "@cardinality": "many" } },
         { "identity.primary": { "@fields": "id" } },
         { "identity.secondary": { "name": "byTitle", "@fields": "title", "@unique": true } }
@@ -80,6 +95,44 @@ public void CreateTable_emits_columns_pk_notnull_and_unique_index()
         Assert.Contains("CREATE TABLE weeks (", sql);
     }
 
+    [Fact]
+    public void CreateTable_emits_foreign_key_for_enforced_reference()
+    {
+        var sql = PostgresSchema.BuildSchema(Load());
+        // Week.fkProgram (@enforce default true) -> a physical FK to programs.id.
+        Assert.Contains(
+            "CONSTRAINT weeks_programId_fk FOREIGN KEY (programId) REFERENCES programs (id)",
+            sql);
+    }
+
+    [Fact]
+    public void CreateTable_omits_foreign_key_for_logical_only_reference()
+    {
+        var sql = PostgresSchema.BuildSchema(Load());
+        Assert.Contains("CREATE TABLE tags (", sql);
+        // Tag.fkProgramLogical is @enforce: false -> no physical FK constraint.
+        Assert.DoesNotContain("CONSTRAINT tags_", sql);
+    }
+
+    [Fact]
+    public void Flattened_object_field_expands_to_prefixed_columns()
+    {
+        var sql = PostgresSchema.BuildSchema(Load());
+        // Program.homeAddress @storage flattened -> Address fields as "homeAddress_*";
+        // the parent object emits no column of its own.
+        Assert.Contains("homeAddress_street varchar(120) NOT NULL", sql);
+        Assert.Contains("homeAddress_city varchar(80)", sql);
+        Assert.DoesNotContain("homeAddress jsonb", sql);
+    }
+
+    [Fact]
+    public void Default_object_field_collapses_to_jsonb_column()
+    {
+        var sql = PostgresSchema.BuildSchema(Load());
+        // Program.config has no @storage -> single jsonb column (back-compat default).
+        Assert.Contains("config jsonb", sql);
+    }
+
     [Fact]
     public void CreateView_emits_select_for_passthrough_projection()
     {
diff --git a/server/csharp/MetaObjects.Codegen/Schema/PostgresSchema.cs b/server/csharp/MetaObjects.Codegen/Schema/PostgresSchema.cs
@@ -49,24 +49,41 @@ public static class PostgresSchema
 
     private static string Col(MetaField f) => f.DbColumn ?? f.Name;
 
-    /// <summary>CREATE TABLE for a writable entity (columns + PK + NOT NULL + UNIQUE).</summary>
-    public static string CreateTable(MetaObject entity)
+    /// <summary>
+    /// CREATE TABLE for a writable entity: scalar columns + object-field storage
+    /// (@storage flattened → prefixed columns; else a single jsonb column) + PK +
+    /// NOT NULL + UNIQUE indexes + FOREIGN KEY constraints (from enforced
+    /// identity.reference children).
+    /// </summary>
+    public static string CreateTable(MetaObject entity, MetaRoot root)
     {
         var table = entity.DbTable ?? entity.Name;
         var pk = entity.PrimaryIdentity();
         var pkCols = (pk?.Fields ?? []).ToHashSet(StringComparer.Ordinal);
 
         var lines = new List<string>();
-        foreach (var f in entity.Fields().Where(f => CSharpNaming.ScalarFor(f.SubType) is not null))
+        foreach (var f in entity.Fields())
         {
-            var notNull = CSharpNaming.IsRequired(entity, f) ? " NOT NULL" : string.Empty;
-            lines.Add($"  {Col(f)} {PgType(f)}{notNull}");
+            if (CSharpNaming.ScalarFor(f.SubType) is not null)
+            {
+                var notNull = CSharpNaming.IsRequired(entity, f) ? " NOT NULL" : string.Empty;
+                lines.Add($"  {Col(f)} {PgType(f)}{notNull}");
+            }
+            else if (f.SubType == FIELD_SUBTYPE_OBJECT)
+            {
+                lines.AddRange(ObjectFieldColumns(entity, f, root));
+            }
         }
         if (pk is not null && pk.Fields.Count > 0)
         {
             var cols = entity.Fields().Where(f => pkCols.Contains(f.Name)).Select(Col);
             lines.Add($"  PRIMARY KEY ({string.Join(", ", cols)})");
         }
+        // FOREIGN KEY constraints from enforced identity.reference children.
+        foreach (var fk in entity.ReferenceIdentities().Where(r => r.Enforce))
+        {
+            if (ForeignKeyClause(entity, fk, root) is { } clause) lines.Add(clause);
+        }
 
         var sb = new StringBuilder();
         sb.AppendLine($"CREATE TABLE {table} (");
@@ -82,6 +99,55 @@ public static string CreateTable(MetaObject entity)
         return sb.ToString();
     }
 
+    // Columns for an object-typed field. @storage flattened expands each nested
+    // scalar field as "{parentCol}_{nestedCol}" (the parent emits no column of its
+    // own); every other storage (jsonb / subdocument / absent) collapses to one
+    // jsonb column — a relational target can't materialize a document store inline.
+    private static IEnumerable<string> ObjectFieldColumns(MetaObject entity, MetaField f, MetaRoot root)
+    {
+        if (f.Storage == STORAGE_FLATTENED && f.ObjectRef is { } oref &&
+            root.FindObject(StripPkg(oref)) is { } nested)
+        {
+            var prefix = Col(f) + "_";
+            foreach (var nf in nested.Fields().Where(n => CSharpNaming.ScalarFor(n.SubType) is not null))
+            {
+                var notNull = CSharpNaming.IsRequired(nested, nf) ? " NOT NULL" : string.Empty;
+                yield return $"  {prefix}{Col(nf)} {PgType(nf)}{notNull}";
+            }
+            yield break;
+        }
+        var topNotNull = CSharpNaming.IsRequired(entity, f) ? " NOT NULL" : string.Empty;
+        yield return $"  {Col(f)} jsonb{topNotNull}";
+    }
+
+    // A table-level FOREIGN KEY constraint for an enforced reference identity.
+    // FK columns keep the reference's declared @fields order; target columns are
+    // the explicit dotted @references fields (multi-col) or the target's primary
+    // identity (single-col / bare form), falling back to "id".
+    private static string? ForeignKeyClause(MetaObject entity, MetaReferenceIdentity fk, MetaRoot root)
+    {
+        if (fk.TargetEntity is not { } targetName || fk.Fields.Count == 0) return null;
+        var target = root.FindObject(StripPkg(targetName));
+        if (target is null) return null;
+
+        var fkCols = fk.Fields.Select(js => ResolveColumn(entity, js)).ToList();
+        var refCols = fk.TargetFields.Count > 1
+            ? fk.TargetFields.Select(tf => ResolveColumn(target, tf)).ToList()
+            : [ResolveColumn(target, ResolvedTargetPkField(target, fk))];
+
+        var name = $"{entity.DbTable ?? entity.Name}_{fkCols[0]}_fk";
+        var refTable = target.DbTable ?? target.Name;
+        return $"  CONSTRAINT {name} FOREIGN KEY ({string.Join(", ", fkCols)}) " +
+               $"REFERENCES {refTable} ({string.Join(", ", refCols)})";
+    }
+
+    // The single target column a reference resolves to: the lone explicit @references
+    // field, else the target's primary-identity first field, else "id".
+    private static string ResolvedTargetPkField(MetaObject target, MetaReferenceIdentity fk) =>
+        fk.TargetFields.Count == 1
+            ? fk.TargetFields[0]
+            : target.PrimaryIdentity()?.Fields.FirstOrDefault() ?? "id";
+
     /// <summary>
     /// CREATE VIEW for a projection. Derives the SELECT from field origins:
     /// passthrough (single base) → a plain column; aggregate (@agg/@of/@via) → a
@@ -242,7 +308,7 @@ public static string BuildSchema(MetaRoot root, Action<string>? warn = null)
         foreach (var e in root.Objects().Where(o => o.IsEntity() && !o.IsReadOnlyProjection())
                      .OrderBy(o => o.Name, StringComparer.Ordinal))
         {
-            sb.AppendLine(CreateTable(e));
+            sb.AppendLine(CreateTable(e, root));
         }
         foreach (var p in root.Objects().Where(o => o.IsReadOnlyProjection())
                      .OrderBy(o => o.Name, StringComparer.Ordinal))
diff --git a/server/csharp/MetaObjects/Meta/MetaField.cs b/server/csharp/MetaObjects/Meta/MetaField.cs
@@ -25,6 +25,20 @@ public string? ObjectRef
         }
     }
 
+    /// <summary>
+    /// Storage strategy for an object-typed field (the <c>@storage</c> attr):
+    /// <c>flattened</c> / <c>jsonb</c> / <c>subdocument</c>, or null when absent
+    /// (a relational target treats absent as single-jsonb-column, per back-compat).
+    /// </summary>
+    public string? Storage
+    {
+        get
+        {
+            var v = OwnAttr(FIELD_ATTR_STORAGE);
+            return v is string s ? s : null;
+        }
+    }
+
     /// <summary>Column name override (the <c>@dbColumn</c> attr).</summary>
     public string? DbColumn
     {
