test(api-contract): cross-port @autoset stamping gate (ADR-0045, #203/#229)

Adds the shared api-contract-conformance gate that verifies the deployed API
surface honors field.timestamp @autoset across all five ports — the "additional
assurance" gate #229 asked for, now achievable because the Kotlin controller
(46d8e54) and Python router (abf48d2) were fixed to stamp above the seam.

Corpus (fixtures/api-contract-conformance/):
- Author gains isolated autoCreatedAt (@autoset:onCreate) + autoUpdatedAt
  (@autoset:onUpdate) fields — existing scenarios untouched (they use subset
  matchers; the only equals is list-empty's []).
- seed.json seeds both to an OLD "2000-01-01" sentinel (equal).
- scenarios/autoset-patch.yaml: PATCH /api/authors/1 → assert
  fieldsNotEqual:[autoCreatedAt, autoUpdatedAt]. A field-vs-field inequality
  (old sentinel vs a 2026 now()) is format- AND timing-agnostic and catches BOTH
  the no-bump and the lost-update (rewrite-created) failure modes — no capture-once
  or literal timestamp matching needed.

Per-port runners (test-only; no generator/product code touched):
- New fieldsEqual/fieldsNotEqual matchers (raw response field-vs-field) in all five
  assertion vocabularies (TS/Python/Kotlin/Java/C#).
- Each hand-rolled reference server stamps @autoset (insert stamps onCreate+onUpdate
  from one now(); update/patch bumps onUpdate, never rewrites onCreate) + serves the
  two new columns; seeds the OLD sentinel via DIRECT insert (not the stamping path).
- Generated-lane harnesses that POST-seed (Kotlin/Java/C#) switched to a direct
  insert of the sentinel, so the generated controller's PATCH-stamp diverges robustly
  (Python/TS already seed directly).

Verified: all five ports pass both lanes (reference + generated) — 26 scenarios × 2
each, including autoset-patch, with every prior scenario green. POST onCreate/onUpdate
stamping stays unit-gated per port (KotlinAutoSetStampingTest, test_router_autoset,
Issue203AutoSetStampingTests, etc.); this corpus gates the drift-prone update path
cross-port.

Refs #203, #229.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeGSV3StPCcJGZNNJ4ZfAb

Author: dmealing

fixtures/api-contract-conformance/README.md

@@ -93,6 +93,8 @@ requests:
 | `envelope`   | the response body is `{ rows, total }` (set `rowsLength` + `total`)    |
 | `error`      | the response body has `error: "<value>"`                               |
 | `empty`      | the response body is empty / null (204 No Content)                     |
+| `fieldsEqual`| the response body is an object; assert the listed field names are all equal to **each other** (raw, field-vs-field — no literal, so timestamp non-determinism is a non-issue). Used by the `@autoSet` gate (#203/ADR-0045). |
+| `fieldsNotEqual`| the response body is an object; assert the two listed fields **differ** from each other. Used by the `@autoSet` gate (e.g. after a PATCH, `autoCreatedAt` (onCreate, preserved) != `autoUpdatedAt` (onUpdate, bumped)). |
 
 Runners are responsible for normalizing `createdAt` (and any other
 non-deterministic fields) before comparison. The keys listed above are

fixtures/api-contract-conformance/meta.json

@@ -10,6 +10,8 @@
           { "field.string":     { "name": "name", "@required": true, "@maxLength": 100, "@filterable": true, "@sortable": true } },
           { "field.string":     { "name": "bio",  "@maxLength": 1000, "@filterable": true, "@sortable": false } },
           { "field.timestamp":  { "name": "createdAt", "@required": true, "@filterable": true, "@sortable": true } },
+          { "field.timestamp":  { "name": "autoCreatedAt", "@autoSet": "onCreate" } },
+          { "field.timestamp":  { "name": "autoUpdatedAt", "@autoSet": "onUpdate" } },
           { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }
         ]
       }}

fixtures/api-contract-conformance/scenarios/autoset-patch.yaml

@@ -0,0 +1,21 @@
+name: autoset-patch
+description: >
+  #203 / ADR-0045 — @autoSet timestamp stamping is honored by the deployed API
+  surface (generated controller/routes AND the reference server). The seeded row
+  starts with autoCreatedAt == autoUpdatedAt (both an old sentinel). A PATCH must
+  bump the onUpdate column (autoUpdatedAt) to now() while leaving the onCreate
+  column (autoCreatedAt) untouched — so the two diverge. Asserted as a field-vs-field
+  inequality (format- and timing-agnostic: old sentinel vs a 2026 now()), which
+  catches BOTH failure modes: not bumping updatedAt, and the lost-update bug of
+  rewriting createdAt on update.
+requests:
+  - id: r1
+    method: PATCH
+    path: /api/authors/1
+    body:
+      name: "Ada L."
+    expect:
+      status: 200
+      body:
+        # autoUpdatedAt bumped to now() (2026); autoCreatedAt preserved (2000 sentinel).
+        fieldsNotEqual: [autoCreatedAt, autoUpdatedAt]

fixtures/api-contract-conformance/seed.json

@@ -1,9 +1,9 @@
 {
   "rows": [
-    { "id": 1, "name": "Ada Lovelace",     "bio": "First computer programmer",       "createdAt": "2026-01-01T10:00:00" },
-    { "id": 2, "name": "Alan Turing",      "bio": null,                              "createdAt": "2026-01-02T10:00:00" },
-    { "id": 3, "name": "Grace Hopper",     "bio": "Invented the compiler",           "createdAt": "2026-01-03T10:00:00" },
-    { "id": 4, "name": "Donald Knuth",     "bio": "The Art of Computer Programming", "createdAt": "2026-01-04T10:00:00" },
-    { "id": 5, "name": "Edsger Dijkstra",  "bio": null,                              "createdAt": "2026-01-05T10:00:00" }
+    { "id": 1, "name": "Ada Lovelace",     "bio": "First computer programmer",       "createdAt": "2026-01-01T10:00:00", "autoCreatedAt": "2000-01-01T00:00:00", "autoUpdatedAt": "2000-01-01T00:00:00" },
+    { "id": 2, "name": "Alan Turing",      "bio": null,                              "createdAt": "2026-01-02T10:00:00", "autoCreatedAt": "2000-01-01T00:00:00", "autoUpdatedAt": "2000-01-01T00:00:00" },
+    { "id": 3, "name": "Grace Hopper",     "bio": "Invented the compiler",           "createdAt": "2026-01-03T10:00:00", "autoCreatedAt": "2000-01-01T00:00:00", "autoUpdatedAt": "2000-01-01T00:00:00" },
+    { "id": 4, "name": "Donald Knuth",     "bio": "The Art of Computer Programming", "createdAt": "2026-01-04T10:00:00", "autoCreatedAt": "2000-01-01T00:00:00", "autoUpdatedAt": "2000-01-01T00:00:00" },
+    { "id": 5, "name": "Edsger Dijkstra",  "bio": null,                              "createdAt": "2026-01-05T10:00:00", "autoCreatedAt": "2000-01-01T00:00:00", "autoUpdatedAt": "2000-01-01T00:00:00" }
   ]
 }

server/csharp/MetaObjects.IntegrationTests/Api/ApiContractAssertions.cs

@@ -1,8 +1,13 @@
 // ApiContractAssertions — assertion vocabulary for api-contract-conformance.
 // The recognized keys (equals / length / ids / names / row / hasId / envelope /
-// error / empty) are the cross-port contract — every per-port runner must
-// implement them identically. See
+// error / empty / fieldsEqual / fieldsNotEqual) are the cross-port contract —
+// every per-port runner must implement them identically. See
 // fixtures/api-contract-conformance/README.md.
+//
+// fieldsEqual / fieldsNotEqual (#203 / ADR-0045, the @autoSet gate) compare RAW
+// response-object fields to EACH OTHER (never a literal): fieldsEqual asserts all
+// listed fields equal one another; fieldsNotEqual asserts the two listed fields
+// differ. Field-vs-field so timestamp non-determinism is a non-issue.
 
 namespace MetaObjects.IntegrationTests.Api;
 
@@ -144,6 +149,44 @@ public static void AssertResponse(string scenarioName, ApiRequest request, int s
                 throw new Xunit.Sdk.XunitException(
                     $"{scenarioName} / {request.Id}: expected numeric id in body, got: {Render(body)}");
         }
+        // #203 / ADR-0045 @autoSet gate — every listed response field must equal EACH OTHER
+        // (raw field-vs-field, no literal). Missing keys compare as null.
+        if (want.TryGetValue("fieldsEqual", out var feObj) && feObj is List<object?> feFields)
+        {
+            if (body is not Dictionary<string, object?> row)
+                throw new Xunit.Sdk.XunitException(
+                    $"{scenarioName} / {request.Id}: expected object for fieldsEqual, got: {Render(body)}");
+            var names = feFields.Select(f => f?.ToString() ?? "").ToList();
+            for (int i = 1; i < names.Count; i++)
+            {
+                row.TryGetValue(names[0], out var v0);
+                row.TryGetValue(names[i], out var vi);
+                if (!StructuralEquals(v0, vi))
+                    throw new Xunit.Sdk.XunitException(
+                        $"{scenarioName} / {request.Id}: expected fields [{string.Join(", ", names)}] all equal, "
+                        + $"but {names[0]}={Render(v0)} != {names[i]}={Render(vi)}");
+            }
+        }
+        // #203 / ADR-0045 @autoSet gate — the two listed response fields must DIFFER from each
+        // other (e.g. after a PATCH, autoCreatedAt (onCreate, preserved) != autoUpdatedAt
+        // (onUpdate, bumped)). Missing keys compare as null.
+        if (want.TryGetValue("fieldsNotEqual", out var fneObj) && fneObj is List<object?> fneFields)
+        {
+            if (body is not Dictionary<string, object?> row)
+                throw new Xunit.Sdk.XunitException(
+                    $"{scenarioName} / {request.Id}: expected object for fieldsNotEqual, got: {Render(body)}");
+            var names = fneFields.Select(f => f?.ToString() ?? "").ToList();
+            if (names.Count != 2)
+                throw new Xunit.Sdk.XunitException(
+                    $"{scenarioName} / {request.Id}: fieldsNotEqual expects exactly two field names, "
+                    + $"got [{string.Join(", ", names)}]");
+            row.TryGetValue(names[0], out var v0);
+            row.TryGetValue(names[1], out var v1);
+            if (StructuralEquals(v0, v1))
+                throw new Xunit.Sdk.XunitException(
+                    $"{scenarioName} / {request.Id}: expected fields {names[0]} and {names[1]} to DIFFER, "
+                    + $"but both = {Render(v0)}");
+        }
     }
 
     /// <summary>

server/csharp/MetaObjects.IntegrationTests/Api/AuthorApiServer.cs

@@ -90,7 +90,12 @@ public static async Task<AuthorApiServer> StartAsync(PostgresContainer pg)
                     id BIGSERIAL PRIMARY KEY,
                     name VARCHAR(100) NOT NULL,
                     bio VARCHAR(1000),
-                    ""createdAt"" TIMESTAMP NOT NULL
+                    ""createdAt"" TIMESTAMP NOT NULL,
+                    -- Issue #203 / ADR-0045: the @autoSet timestamp columns (onCreate / onUpdate).
+                    -- Nullable (not @required); the seed writes them verbatim, create stamps both,
+                    -- update bumps only autoUpdatedAt.
+                    ""autoCreatedAt"" TIMESTAMP,
+                    ""autoUpdatedAt"" TIMESTAMP
                 )";
             await cmd.ExecuteNonQueryAsync();
         }
@@ -135,11 +140,19 @@ public async Task ApplySeedAsync(IReadOnlyList<Dictionary<string, object?>> rows
         {
             await using var ins = c.CreateCommand();
             ins.CommandText =
-                "INSERT INTO \"authors\" (id, name, bio, \"createdAt\") VALUES (@id, @name, @bio, @ct)";
+                "INSERT INTO \"authors\" (id, name, bio, \"createdAt\", \"autoCreatedAt\", \"autoUpdatedAt\") "
+                + "VALUES (@id, @name, @bio, @ct, @ac, @au)";
             ins.Parameters.AddWithValue("@id", Convert.ToInt64(r["id"]));
             ins.Parameters.AddWithValue("@name", (string)r["name"]!);
             ins.Parameters.AddWithValue("@bio", r["bio"] is string b ? b : (object)DBNull.Value);
             ins.Parameters.AddWithValue("@ct", ParseTimestamp((string)r["createdAt"]!));
+            // Issue #203 / ADR-0045 — the seed writes the OLD @autoSet sentinel VERBATIM (a direct
+            // insert, NOT a stamping create) so the seeded row keeps the old value; the PATCH then
+            // bumps autoUpdatedAt while autoCreatedAt stays old → a robust field-vs-field divergence.
+            ins.Parameters.AddWithValue("@ac",
+                r.GetValueOrDefault("autoCreatedAt") is string ac ? ParseTimestamp(ac) : (object)DBNull.Value);
+            ins.Parameters.AddWithValue("@au",
+                r.GetValueOrDefault("autoUpdatedAt") is string au ? ParseTimestamp(au) : (object)DBNull.Value);
             await ins.ExecuteNonQueryAsync();
         }
         await using var bump = c.CreateCommand();
@@ -261,7 +274,8 @@ private async Task ListAuthorsAsync(
         var bindParams = new List<object?>();
         string whereClause = BuildWhere(filter.Predicates, bindParams);
 
-        var sql = new StringBuilder("SELECT id, name, bio, \"createdAt\" FROM \"authors\"");
+        var sql = new StringBuilder(
+            "SELECT id, name, bio, \"createdAt\", \"autoCreatedAt\", \"autoUpdatedAt\" FROM \"authors\"");
         sql.Append(whereClause);
         sql.Append(" ORDER BY \"").Append(sortField).Append("\" ").Append(sortDir);
         if (limit is int lim) sql.Append(" LIMIT ").Append(lim);
@@ -473,7 +487,7 @@ private async Task GetAuthorAsync(HttpListenerContext ctx, string idStr)
         await using var c = new NpgsqlConnection(_pg.ConnectionString);
         await c.OpenAsync();
         await using var cmd = c.CreateCommand();
-        cmd.CommandText = "SELECT id, name, bio, \"createdAt\" FROM \"authors\" WHERE id = @id";
+        cmd.CommandText = "SELECT id, name, bio, \"createdAt\", \"autoCreatedAt\", \"autoUpdatedAt\" FROM \"authors\" WHERE id = @id";
         cmd.Parameters.AddWithValue("@id", id.Value);
         await using var rdr = await cmd.ExecuteReaderAsync();
         if (!await rdr.ReadAsync())
@@ -508,21 +522,28 @@ private async Task CreateAuthorAsync(HttpListenerContext ctx)
             return;
         }
         long newId;
+        // Issue #203 / ADR-0045 — stamp BOTH @autoSet columns from ONE now(), ignoring any
+        // caller-supplied value (a fresh row's autoUpdatedAt == its autoCreatedAt). Unspecified
+        // kind to match the plain-TIMESTAMP columns (the seed's ParseTimestamp yields the same).
+        var autoNow = DateTime.SpecifyKind(DateTimeOffset.UtcNow.UtcDateTime, DateTimeKind.Unspecified);
         await using var c = new NpgsqlConnection(_pg.ConnectionString);
         await c.OpenAsync();
         await using (var ins = c.CreateCommand())
         {
             ins.CommandText =
-                "INSERT INTO \"authors\" (name, bio, \"createdAt\") VALUES (@name, @bio, @ct) RETURNING id";
+                "INSERT INTO \"authors\" (name, bio, \"createdAt\", \"autoCreatedAt\", \"autoUpdatedAt\") "
+                + "VALUES (@name, @bio, @ct, @ac, @au) RETURNING id";
             ins.Parameters.AddWithValue("@name", body.GetValueOrDefault("name") as string ?? "");
             ins.Parameters.AddWithValue("@bio", body.GetValueOrDefault("bio") is string b ? b : (object)DBNull.Value);
             ins.Parameters.AddWithValue("@ct", ParseTimestamp((string)body["createdAt"]!));
+            ins.Parameters.AddWithValue("@ac", autoNow);
+            ins.Parameters.AddWithValue("@au", autoNow);
             newId = Convert.ToInt64(await ins.ExecuteScalarAsync());
         }
         Dictionary<string, object?> row;
         await using (var sel = c.CreateCommand())
         {
-            sel.CommandText = "SELECT id, name, bio, \"createdAt\" FROM \"authors\" WHERE id = @id";
+            sel.CommandText = "SELECT id, name, bio, \"createdAt\", \"autoCreatedAt\", \"autoUpdatedAt\" FROM \"authors\" WHERE id = @id";
             sel.Parameters.AddWithValue("@id", newId);
             await using var rdr = await sel.ExecuteReaderAsync();
             await rdr.ReadAsync();
@@ -572,6 +593,12 @@ private async Task UpdateAuthorAsync(HttpListenerContext ctx, string idStr)
             await SendJsonAsync(ctx, 400, new Dictionary<string, object?> { ["error"] = "validation" });
             return;
         }
+        // Issue #203 / ADR-0045 — bump the onUpdate @autoSet column (autoUpdatedAt) to now();
+        // autoCreatedAt (onCreate) is NEVER written on update (the write-once created-at contract),
+        // so after a PATCH the two diverge. Appended AFTER the empty-body guard so a no-op PATCH
+        // still 400s per FR-035. Unspecified kind to match the plain-TIMESTAMP column.
+        sets.Add("\"autoUpdatedAt\" = @p" + vals.Count);
+        vals.Add(DateTime.SpecifyKind(DateTimeOffset.UtcNow.UtcDateTime, DateTimeKind.Unspecified));
         int updated;
         await using var c = new NpgsqlConnection(_pg.ConnectionString);
         await c.OpenAsync();
@@ -592,7 +619,7 @@ private async Task UpdateAuthorAsync(HttpListenerContext ctx, string idStr)
         Dictionary<string, object?> row;
         await using (var sel = c.CreateCommand())
         {
-            sel.CommandText = "SELECT id, name, bio, \"createdAt\" FROM \"authors\" WHERE id = @id";
+            sel.CommandText = "SELECT id, name, bio, \"createdAt\", \"autoCreatedAt\", \"autoUpdatedAt\" FROM \"authors\" WHERE id = @id";
             sel.Parameters.AddWithValue("@id", id.Value);
             await using var rdr = await sel.ExecuteReaderAsync();
             await rdr.ReadAsync();
@@ -621,23 +648,25 @@ private async Task DeleteAuthorAsync(HttpListenerContext ctx, string idStr)
 
     private static Dictionary<string, object?> RowToMap(NpgsqlDataReader rdr)
     {
-        var row = new Dictionary<string, object?>(StringComparer.Ordinal)
+        return new Dictionary<string, object?>(StringComparer.Ordinal)
         {
             ["id"] = rdr.GetInt64(rdr.GetOrdinal("id")),
             ["name"] = rdr.GetString(rdr.GetOrdinal("name")),
             ["bio"] = rdr.IsDBNull(rdr.GetOrdinal("bio")) ? null : rdr.GetString(rdr.GetOrdinal("bio")),
+            ["createdAt"] = ReadTimestamp(rdr, "createdAt"),
+            // Issue #203 / ADR-0045 — the @autoSet columns surface on the wire so the
+            // autoset-patch scenario can assert autoCreatedAt (onCreate, preserved) !=
+            // autoUpdatedAt (onUpdate, bumped) after a PATCH.
+            ["autoCreatedAt"] = ReadTimestamp(rdr, "autoCreatedAt"),
+            ["autoUpdatedAt"] = ReadTimestamp(rdr, "autoUpdatedAt"),
         };
-        int ctOrd = rdr.GetOrdinal("createdAt");
-        if (rdr.IsDBNull(ctOrd))
-        {
-            row["createdAt"] = null;
-        }
-        else
-        {
-            var dt = rdr.GetDateTime(ctOrd);
-            row["createdAt"] = dt.ToString(TimestampFmt, CultureInfo.InvariantCulture);
-        }
-        return row;
+    }
+
+    /// <summary>Read a nullable TIMESTAMP column, formatted in the wire form (no zone), or null.</summary>
+    private static object? ReadTimestamp(NpgsqlDataReader rdr, string column)
+    {
+        int ord = rdr.GetOrdinal(column);
+        return rdr.IsDBNull(ord) ? null : rdr.GetDateTime(ord).ToString(TimestampFmt, CultureInfo.InvariantCulture);
     }
 
     private static async Task<object?> ReadJsonBodyAsync(HttpListenerContext ctx)

server/csharp/MetaObjects.IntegrationTests/Api/GeneratedAuthorServerFactory.cs

@@ -85,7 +85,12 @@ bio VARCHAR(1000),
                     -- ADR-0036 Wave 2: a default field.timestamp is an absolute instant →
                     -- the generated EF model binds CreatedAt to DateTimeOffset, which Npgsql
                     -- reads from a `timestamp with time zone` (timestamptz) column.
-                    ""createdAt"" TIMESTAMPTZ NOT NULL
+                    ""createdAt"" TIMESTAMPTZ NOT NULL,
+                    -- Issue #203 / ADR-0045: the @autoSet timestamp columns (onCreate / onUpdate).
+                    -- Not @required → nullable DateTimeOffset? in the generated EF model; the
+                    -- generated CRUD stamps them (insert stamps both, update bumps autoUpdatedAt).
+                    ""autoCreatedAt"" TIMESTAMPTZ,
+                    ""autoUpdatedAt"" TIMESTAMPTZ
                 )";
             await cmd.ExecuteNonQueryAsync();
         }
@@ -285,11 +290,19 @@ public async Task ApplySeedAsync(IReadOnlyList<Dictionary<string, object?>> rows
         {
             await using var ins = c.CreateCommand();
             ins.CommandText =
-                "INSERT INTO \"authors\" (id, name, bio, \"createdAt\") VALUES (@id, @name, @bio, @ct)";
+                "INSERT INTO \"authors\" (id, name, bio, \"createdAt\", \"autoCreatedAt\", \"autoUpdatedAt\") "
+                + "VALUES (@id, @name, @bio, @ct, @ac, @au)";
             ins.Parameters.AddWithValue("@id", Convert.ToInt64(r["id"]));
             ins.Parameters.AddWithValue("@name", (string)r["name"]!);
             ins.Parameters.AddWithValue("@bio", r["bio"] is string b ? b : (object)DBNull.Value);
             ins.Parameters.AddWithValue("@ct", ParseTimestamp((string)r["createdAt"]!));
+            // Issue #203 / ADR-0045 — seed the OLD @autoSet sentinel via a DIRECT insert (NOT the
+            // stamping generated POST) so the seeded row keeps the old value; the generated PATCH
+            // then bumps autoUpdatedAt while autoCreatedAt stays old → the asserted divergence.
+            ins.Parameters.AddWithValue("@ac",
+                r.GetValueOrDefault("autoCreatedAt") is string ac ? ParseTimestamp(ac) : (object)DBNull.Value);
+            ins.Parameters.AddWithValue("@au",
+                r.GetValueOrDefault("autoUpdatedAt") is string au ? ParseTimestamp(au) : (object)DBNull.Value);
             await ins.ExecuteNonQueryAsync();
         }
         await using var bump = c.CreateCommand();