fix(datetime): drop format keyword from schema, fix fractional-second warning

Two findings from codex review of the :datetime feature.

[P2] Remove `format: "date-time"` from the JSON Schema for `:datetime`.
OpenAI's strict-mode structured output (the very provider I optimized
for) rejects unsupported keywords including `format`, which would 400
any request that paired `:datetime` with `response_format: {type:
"json_schema", strict: true}` BEFORE local coercion got a chance to
run. Schema is now a plain `{"type": "string"}`. Local coercion still
validates ISO 8601 + offset, and the prompt-side example value
("2026-05-03T09:14:00Z") covers the LLM-guidance role that `format`
would have played.

[P3] Fix the non-UTC warning for fractional-second timestamps. The old
shape check used a binary pattern matching exactly 19 chars before the
offset (`<<_::binary-19, "Z", _::binary>>`). Inputs like
"2026-05-03T09:14:00.123Z" have 23 chars before the Z and were falsely
flagged as non-UTC even though they're valid UTC. Switched to checking
the parsed offset (0 = UTC) returned by `DateTime.from_iso8601/1`,
which is the source of truth and indifferent to fractional seconds.

Tests:
- Updated the schema-shape assertions in signature_test.exs and
  text_mode_json_test.exs to expect plain string schema (no format).
- Two new regression tests in coercion_test.exs covering
  "...Z" and "...+00:00" with fractional seconds, asserting no
  spurious non-UTC warning.

Docs: signature-syntax.md updated to explain why format is omitted
(strict-mode compatibility) instead of overclaiming the server-side
enforcement benefit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: andreasronge

docs/signature-syntax.md

@@ -71,10 +71,12 @@ DateTime.diff(DateTime.utc_now(), step.return["at"])  # works directly
 | `"2026-05-03T11:14:00+02:00"` | Shifted to `~U[2026-05-03 09:14:00Z]` with a "non-UTC offset" warning |
 | `"2026-05-03T09:14:00"` (no offset) | Validation error — naive strings are ambiguous and rejected at the type boundary |
 
-The JSON Schema sent to the LLM provider includes `format: "date-time"`. OpenAI's
-structured output enforces this server-side; Anthropic treats it as guidance.
-Either way, coercion validates the string locally so an invalid date never
-reaches the caller.
+The JSON Schema sent to the LLM provider is a plain `{"type": "string"}` —
+the `format: "date-time"` keyword is omitted because OpenAI's strict-mode
+structured output rejects unsupported keywords and would 400 the request.
+Local coercion validates the ISO 8601 + offset shape, so an invalid date
+never reaches the caller. The prompt-side example value
+(`"2026-05-03T09:14:00Z"`) covers the LLM-guidance role.
 
 **When to pick `:string` vs `:datetime`:**
 - `:datetime` if your code does anything with the value (compare, diff, format,

lib/ptc_runner/sub_agent/signature.ex

@@ -204,11 +204,16 @@ defmodule PtcRunner.SubAgent.Signature do
   def type_to_json_schema(:float), do: %{"type" => "number"}
   def type_to_json_schema(:bool), do: %{"type" => "boolean"}
   def type_to_json_schema(:keyword), do: %{"type" => "string"}
-  # `:datetime` is RFC 3339 / ISO 8601 with offset. OpenAI's structured output
-  # respects `format: "date-time"` server-side; Anthropic treats it as guidance
-  # in tool schemas. Either way, coercion validates the string locally so an
-  # invalid date never reaches the caller.
-  def type_to_json_schema(:datetime), do: %{"type" => "string", "format" => "date-time"}
+  # `:datetime` ships as a plain `{"type": "string"}` to providers. We initially
+  # emitted `format: "date-time"` here, but OpenAI's strict-mode structured
+  # output (and strict tool schemas) reject any keyword outside their supported
+  # subset, including `format`. Strict-mode requests would 400 before our
+  # local DateTime coercion got a chance to run. Local coercion does the
+  # actual ISO 8601 + offset validation; the type's value to the caller (a
+  # `%DateTime{}` struct, not a string) is what makes `:datetime` more than
+  # `:string`. The prompt-side example value (`"2026-05-03T09:14:00Z"`)
+  # covers the LLM-guidance role that `format` would have played.
+  def type_to_json_schema(:datetime), do: %{"type" => "string"}
   # Bedrock requires input_schema to have a "type" field, so :any uses "object"
   def type_to_json_schema(:any), do: %{"type" => "object"}
   def type_to_json_schema(:map), do: %{"type" => "object"}

lib/ptc_runner/sub_agent/signature/coercion.ex

@@ -162,9 +162,13 @@ defmodule PtcRunner.SubAgent.Signature.Coercion do
 
   defp coerce_impl(value, :datetime) when is_binary(value) do
     case DateTime.from_iso8601(value) do
-      {:ok, dt, _offset} ->
+      {:ok, dt, offset_seconds} ->
+        # Use the parsed offset (in seconds) to decide whether to warn, NOT a
+        # pattern match on the raw string shape — fractional seconds shift the
+        # offset characters, so `~r/^.{19}Z/` would false-positive on inputs
+        # like "2026-05-03T09:14:00.123Z" even though they're valid UTC.
         {:ok, DateTime.shift_zone!(dt, "Etc/UTC"),
-         maybe_warn_non_utc(value, ["normalized to UTC"])}
+         offset_warnings(offset_seconds, ["normalized to UTC"])}
 
       {:error, :missing_offset} ->
         {:error,
@@ -446,10 +450,13 @@ defmodule PtcRunner.SubAgent.Signature.Coercion do
   # UTC. The agent's caller still gets a UTC `%DateTime{}` (the type's
   # canonical form), but knowing the model picked a non-UTC zone is useful
   # for prompt-tuning.
-  defp maybe_warn_non_utc(<<_::binary-19, "Z", _::binary>>, base), do: base
-  defp maybe_warn_non_utc(<<_::binary-19, "+00:00", _::binary>>, base), do: base
-  defp maybe_warn_non_utc(<<_::binary-19, "-00:00", _::binary>>, base), do: base
-
-  defp maybe_warn_non_utc(_other, base),
+  #
+  # Driven by the offset returned by `DateTime.from_iso8601/1` (seconds from
+  # UTC) rather than the raw string shape — fractional-second timestamps
+  # would otherwise false-positive a non-UTC warning on "...Z" / "+00:00"
+  # inputs because they shift the offset chars beyond a fixed binary pattern.
+  defp offset_warnings(0, base), do: base
+
+  defp offset_warnings(_offset, base),
     do: base ++ ["non-UTC offset in datetime, normalized to UTC"]
 end

test/ptc_runner/sub_agent/signature/coercion_test.exs

@@ -371,6 +371,25 @@ defmodule PtcRunner.SubAgent.Signature.CoercionTest do
       assert "non-UTC offset in datetime, normalized to UTC" in warnings
     end
 
+    test "fractional-second UTC strings do NOT trigger a spurious non-UTC warning" do
+      # Regression: the previous binary-pattern shape check
+      # (`<<_::binary-19, "Z", _::binary>>`) only matched at exactly 19 chars
+      # before the offset. Inputs like "2026-05-03T09:14:00.123Z" have 23
+      # chars, so they got falsely flagged as non-UTC. Fixed by basing the
+      # warning on the parsed offset (0 = UTC) instead of string shape.
+      assert {:ok, _dt, warnings} =
+               Coercion.coerce("2026-05-03T09:14:00.123Z", :datetime, [])
+
+      refute "non-UTC offset in datetime, normalized to UTC" in warnings
+    end
+
+    test "fractional-second +00:00 offset is also recognized as UTC" do
+      assert {:ok, _dt, warnings} =
+               Coercion.coerce("2026-05-03T09:14:00.123+00:00", :datetime, [])
+
+      refute "non-UTC offset in datetime, normalized to UTC" in warnings
+    end
+
     test "%DateTime{} passes through unchanged" do
       assert {:ok, ~U[2026-05-03 09:14:00Z], []} =
                Coercion.coerce(~U[2026-05-03 09:14:00Z], :datetime, [])

test/ptc_runner/sub_agent/signature_test.exs

@@ -326,15 +326,19 @@ defmodule PtcRunner.SubAgent.SignatureTest do
              ":any schema must have 'type' field for Bedrock compatibility (currently returns #{inspect(schema)})"
     end
 
-    test ":datetime emits {type: string, format: date-time}" do
+    test ":datetime emits a plain string schema (no `format` keyword)" do
+      # OpenAI strict-mode structured output rejects unsupported keywords like
+      # `format`. Local coercion does the actual ISO 8601 + offset validation,
+      # so the schema stays minimal for provider compatibility.
       {:ok, sig} = Signature.parse("() -> :datetime")
-      assert %{"type" => "string", "format" => "date-time"} = Signature.to_json_schema(sig)
+      assert %{"type" => "string"} = Signature.to_json_schema(sig)
+      refute Map.has_key?(Signature.to_json_schema(sig), "format")
     end
 
-    test ":datetime inside a map field carries the format down" do
+    test ":datetime inside a map field also emits plain string (no format)" do
       {:ok, sig} = Signature.parse("() -> {at :datetime, who :string}")
       schema = Signature.to_json_schema(sig)
-      assert schema["properties"]["at"] == %{"type" => "string", "format" => "date-time"}
+      assert schema["properties"]["at"] == %{"type" => "string"}
       assert schema["properties"]["who"] == %{"type" => "string"}
     end
   end

test/ptc_runner/sub_agent/text_mode_json_test.exs

@@ -1024,11 +1024,11 @@ defmodule PtcRunner.SubAgent.TextModeJsonTest do
       assert step.fail.message =~ "datetime"
     end
 
-    test "JSON Schema generated for :datetime carries format: date-time" do
+    test "JSON Schema for :datetime is a plain string (provider-strict-mode safe)" do
       alias PtcRunner.SubAgent.Signature
       agent = SubAgent.new(prompt: "?", output: :text, signature: "{at :datetime}")
       schema = Signature.to_json_schema(agent.parsed_signature)
-      assert schema["properties"]["at"] == %{"type" => "string", "format" => "date-time"}
+      assert schema["properties"]["at"] == %{"type" => "string"}
     end
   end
 end