@@ -192,6 +192,21 @@ edit (two registered `description` strings) and was ruled a hold, as 1.0.4's was
   second C#-only key would be an addition to a cross-port wire contract. Non-TPH entities are
   byte-identical.
 
+- **C#: `field.timestamp` crossed the wire as `+00:00` rather than the documented `Z`.**
+  `docs/features/api-contract.md` spells a timestamp ISO 8601 with the UTC designator;
+  System.Text.Json's default for `DateTimeOffset` renders UTC as a numeric zero offset. Both
+  are valid ISO 8601, which is why it went unnoticed — but the cross-port gate is a BYTE
+  comparison of the same `timestamptz` row read by five ports, and two spellings are two
+  answers. `MetaObjects.Codegen.Runtime.Iso8601TimestampConverter` writes UTC with `Z`
+  (fractional seconds only when the instant has them, so a whole-second value round-trips to
+  the string it arrived as) and reads any ISO 8601 spelling, treating an offset-less value as
+  UTC rather than as server local time. Register it on `ConfigureHttpJsonOptions` beside
+  `JsonStringEnumConverter`; the generated handlers deserialize with the app's CONFIGURED
+  options precisely so a host registration reaches them. A near-copy previously existed only
+  inside the integration-test project, where an adopter never saw it — and that copy did not
+  produce the documented spelling either (`DateTimeOffset.ToString("o")` keeps the numeric
+  offset at UTC; reaching `Z` needs the `UtcDateTime`).
+
 - **C#: a constraint violation answered 500 instead of 409.** A generated CRUD route had no
   try/catch around `SaveChangesAsync`, so a client-supplied foreign key naming no row, or a
   value duplicating a unique one, reached ASP.NET's default handler and came back as a bare
 
@@ -0,0 +1,91 @@
+// Iso8601TimestampConverter — the field.timestamp wire spelling.
+//
+// docs/features/api-contract.md pins ISO 8601 with a timezone, spelled with the UTC
+// designator. System.Text.Json's default renders UTC as `+00:00` instead, and both forms
+// are valid ISO 8601 — which is why this survived: nothing errors, and the permissive
+// "ISO 8601 with timezone" assertions accept either. The cross-port gate is a BYTE
+// comparison of the same timestamptz row read by five ports, so two spellings are two
+// different answers.
+
+using System.Text.Json;
+using MetaObjects.Codegen.Runtime;
+using Xunit;
+
+namespace MetaObjects.Codegen.Tests;
+
+public class Iso8601TimestampConverterTests
+{
+    private static readonly JsonSerializerOptions Options = Build();
+
+    private static JsonSerializerOptions Build()
+    {
+        var o = new JsonSerializerOptions();
+        o.Converters.Add(new Iso8601TimestampConverter());
+        return o;
+    }
+
+    private static string Write(DateTimeOffset value) => JsonSerializer.Serialize(value, Options);
+    private static DateTimeOffset Read(string json) => JsonSerializer.Deserialize<DateTimeOffset>(json, Options);
+
+    [Fact]
+    public void A_utc_instant_writes_the_Z_designator_not_a_zero_offset()
+    {
+        // The whole point. DateTimeOffset.ToString("o") — including the copy that lived in
+        // the integration-test host — writes +00:00 here, because a DateTimeOffset formats
+        // its own numeric offset even when that offset is zero.
+        Assert.Equal("\"2026-09-20T12:10:00Z\"", Write(new DateTimeOffset(2026, 9, 20, 12, 10, 0, TimeSpan.Zero)));
+    }
+
+    [Fact]
+    public void A_non_utc_instant_is_normalized_to_utc()
+    {
+        // Same instant, written the one way: 14:10+02:00 is 12:10Z.
+        Assert.Equal(
+            "\"2026-09-20T12:10:00Z\"",
+            Write(new DateTimeOffset(2026, 9, 20, 14, 10, 0, TimeSpan.FromHours(2))));
+    }
+
+    [Fact]
+    public void Sub_second_precision_is_kept_at_millisecond_resolution()
+    {
+        Assert.Equal(
+            "\"2026-09-20T12:10:00.123Z\"",
+            Write(new DateTimeOffset(2026, 9, 20, 12, 10, 0, 123, TimeSpan.Zero)));
+    }
+
+    [Fact]
+    public void A_whole_second_round_trips_to_the_string_it_came_from()
+    {
+        // Stability is the reason `.000` is not padded on: a client sends a whole-second
+        // instant and reads back the same bytes, so a cross-port byte comparison is not
+        // deciding between two spellings of one value.
+        const string wire = "\"2026-09-20T12:10:00Z\"";
+        Assert.Equal(wire, Write(Read(wire)));
+    }
+
+    [Theory]
+    [InlineData("\"2026-09-20T12:10:00Z\"")]
+    [InlineData("\"2026-09-20T12:10:00+00:00\"")]
+    [InlineData("\"2026-09-20T14:10:00+02:00\"")]
+    public void Every_iso_8601_spelling_of_one_instant_reads_as_that_instant(string wire)
+    {
+        Assert.Equal(new DateTimeOffset(2026, 9, 20, 12, 10, 0, TimeSpan.Zero), Read(wire));
+    }
+
+    [Fact]
+    public void A_value_with_no_offset_is_read_as_utc_not_as_server_local_time()
+    {
+        // A naive string must mean the same instant whatever machine deserializes it —
+        // the only reading that survives five ports on five hosts. Without
+        // AssumeUniversal this is the local time of whoever happened to parse it.
+        Assert.Equal(
+            new DateTimeOffset(2026, 9, 20, 12, 10, 0, TimeSpan.Zero),
+            Read("\"2026-09-20T12:10:00\""));
+    }
+
+    [Fact]
+    public void A_null_is_a_json_error_not_a_default_instant()
+    {
+        Assert.Throws<JsonException>(() => Read("null"));
+    }
+}
@@ -0,0 +1,76 @@
+// Iso8601TimestampConverter — the wire spelling of a field.timestamp.
+//
+// `docs/features/api-contract.md` states that a field.timestamp crosses the wire as ISO
+// 8601 WITH A TIMEZONE, spelled with the UTC designator. System.Text.Json's default for
+// DateTimeOffset is the round-trip form, which renders UTC as `+00:00`:
+//
+//     default  2026-09-20T12:10:00+00:00
+//     contract 2026-09-20T12:10:00Z
+//
+// Both are valid ISO 8601, which is why this went unnoticed: nothing errored, and the
+// permissive "ISO 8601 with timezone" assertions accept either. It matters because the
+// SAME timestamptz row is read by five ports and the cross-port gate is a BYTE
+// comparison — two renderings of one instant are two different answers.
+//
+// The generated CRUD handlers deserialize with the app's CONFIGURED SerializerOptions
+// precisely so a host registration like this reaches them:
+//
+//     builder.Services.ConfigureHttpJsonOptions(o =>
+//         o.SerializerOptions.Converters.Add(new Iso8601TimestampConverter()));
+//
+// It was previously hand-written per test host inside the integration-test project —
+// where an adopter never sees it, and where the copy did not in fact produce the
+// documented spelling (`DateTimeOffset.ToString("o")` keeps the numeric offset even at
+// UTC; reaching `Z` needs the UtcDateTime).
+
+using System.Globalization;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace MetaObjects.Codegen.Runtime;
+
+/// <summary>
+/// Reads and writes <see cref="DateTimeOffset"/> in the api contract's wire spelling:
+/// ISO 8601, normalized to UTC, with the <c>Z</c> designator.
+/// </summary>
+public sealed class Iso8601TimestampConverter : JsonConverter<DateTimeOffset>
+{
+    /// <summary>
+    /// Parse any ISO 8601 instant and normalize it to UTC. A value with NO offset is read
+    /// as already-UTC rather than as server local time — a naive string means the same
+    /// instant whatever machine happens to deserialize it, which is the only reading that
+    /// survives five ports on five hosts.
+    /// </summary>
+    public override DateTimeOffset Read(
+        ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        var raw = reader.GetString();
+        if (raw is null) throw new JsonException("expected an ISO 8601 timestamp string");
+        return DateTimeOffset.Parse(
+            raw, CultureInfo.InvariantCulture,
+            DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal);
+    }
+
+    /// <summary>
+    /// Write as UTC with the <c>Z</c> designator, and with fractional seconds only when
+    /// the instant HAS them.
+    /// <para>
+    /// Sub-second precision is emitted at millisecond resolution when non-zero and omitted
+    /// entirely when zero, rather than always padding `.000`: a whole-second instant reads
+    /// back as the string the client sent it as, so a round-trip is stable and a byte
+    /// comparison across ports is not deciding between two spellings of the same value.
+    /// </para>
+    /// </summary>
+    public override void Write(
+        Utf8JsonWriter writer, DateTimeOffset value, JsonSerializerOptions options)
+    {
+        // .UtcDateTime, not .ToUniversalTime(): a DateTimeOffset formats its own numeric
+        // offset even when that offset is zero, so "o" on a UTC DateTimeOffset still spells
+        // +00:00. Only a DateTime with Kind=Utc renders the Z.
+        var utc = value.UtcDateTime;
+        var format = utc.Millisecond == 0 && utc.Ticks % TimeSpan.TicksPerSecond == 0
+            ? "yyyy-MM-dd'T'HH:mm:ss'Z'"
+            : "yyyy-MM-dd'T'HH:mm:ss.fff'Z'";
+        writer.WriteStringValue(utc.ToString(format, CultureInfo.InvariantCulture));
+    }
+}