docs(api-contract): the real field.timestamp wire form, and field.time

The Tier 1 type-encoding table mandated `YYYY-MM-DDTHH:mm:ss.sssZ` for every
`field.timestamp`. No port emits that, and the table was wrong three ways:

1. `.sss` unconditionally. The rule every port byte-matches — pinned by
   `fixtures/persistence-conformance/normalization.md` — is millisecond
   resolution, TRUNCATED, trailing zeros stripped, and the fraction and its `.`
   omitted entirely when the sub-second value is zero. A whole-second instant is
   `2026-05-25T14:30:00Z`, never `...:00.000Z`.

2. One timestamp row, which silently contradicted ADR-0036 Wave 2 (merged):
   `field.timestamp` is an instant, tz-aware BY DEFAULT, so it carries `Z`;
   `@localTime: true` is the naive wall-clock opt-out and carries NO zone. The
   doc never mentioned `@localTime`. Both rows now exist, and the `Z` is called
   out as the discriminator between TIMESTAMPTZ and TIMESTAMP — eliding it for
   the first or adding it to the second is what makes a response compare unequal.

3. `field.time` was absent from the table outright. Added (`HH:MM:SS[.fff]`).

The doc now defers to normalization.md as the single source of truth instead of
restating the rule a third time and drifting again; only the two properties that
decide byte-equality are repeated, and they are labelled as repetition.

Ruled by the maintainer after the adopter estate surfaced the disagreement: the
ports' behavior stands, the doc changes. Following the doc literally would have
emitted `.000Z` and turned TypeScript red on a scenario it currently passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015NrWUxA6euwvnFcwKxcK6A

Author: dmealing

docs/features/api-contract.md

@@ -252,7 +252,9 @@ for the one-line change.
 | `field.int`, `field.long`, `field.double` | number | `long` MAY be string on overflow; defer to per-port docs. |
 | `field.boolean` | boolean | – |
 | `field.date` | string | ISO 8601 calendar date (`YYYY-MM-DD`). |
-| `field.timestamp` | string | ISO 8601 with timezone (`YYYY-MM-DDTHH:mm:ss.sssZ`). |
+| `field.time` | string | `HH:MM:SS[.fff]`. |
+| `field.timestamp` | string | Instant, tz-aware by default (ADR-0036 Wave 2) — `YYYY-MM-DDTHH:MM:SS[.fff]Z`, **always UTC**. |
+| `field.timestamp` (`@localTime: true`) | string | Naive wall clock — `YYYY-MM-DDTHH:MM:SS[.fff]`, **no `Z`**. |
 | `field.currency` | **integer minor units** | Cents for USD, yen for JPY. Float arithmetic is forbidden. Server never formats. |
 | `field.object` (`@storage: jsonb`) | object | Nested per the sub-object schema. |
 | `field.object` (`@storage: flattened`) | object | Same JSON shape — only the storage differs. |
@@ -263,6 +265,22 @@ expects integer minor units on the wire, and the
 each port's codegen output. Float arithmetic for money has bitten
 every language at least once.
 
+The temporal spellings above are **not** this document's to define — they are
+the cross-port wire forms pinned by
+[`fixtures/persistence-conformance/normalization.md`](../../fixtures/persistence-conformance/normalization.md),
+which every port byte-matches. Two properties of that rule are easy to get
+wrong and are restated here only because they decide whether a response
+compares equal:
+
+- **The `Z` discriminates the two timestamp kinds.** Never elide it for a
+  default (tz-aware) `field.timestamp`, and never add it for an
+  `@localTime: true` one. The suffix is what tells `TIMESTAMPTZ` from
+  `TIMESTAMP`.
+- **Sub-seconds are millisecond resolution, truncated, with no trailing
+  zeros** — and the fractional component *and its `.`* are **omitted
+  entirely when zero**. A whole-second instant is `2026-05-25T14:30:00Z`,
+  never `2026-05-25T14:30:00.000Z`.
+
 ### Error response
 
 Non-2xx responses MUST return: