Document and test pendulum.DateTime propagation through channels

The client itself does no datetime parsing — all time handling is
delegated to python-oa3. tests/test_time_propagation.py locks in
end-to-end behavior through MqttChannel and WebhookChannel parse
paths: pendulum.DateTime is surfaced, and the wire offset (Z,
+00:00, -07:00, +05:30) is preserved without normalization.

README gains a "Time and timezones" section pointing at python-oa3
as the canonical specification, with a parity note for clj-oa3-client.

Closes OA3C-xdt. Wave 2 of the cross-repo ZonedDateTime migration.

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

Author: dcj

README.md

@@ -339,6 +339,27 @@ When VenClient stops (via `stop()` or context manager exit), all channels are st
 | `time` | `float` | Unix timestamp |
 | `raw_payload` | `bytes` | Original request body |
 
+## Time and timezones
+
+`python-oa3-client` does no datetime parsing of its own — all time handling is
+delegated to [openadr3](https://github.com/grid-coordination/python-oa3),
+which is the reference compliant implementation of the cross-implementation
+zone-handling rule.
+
+- Datetime fields on coerced entities (e.g. `event.created`,
+  `interval_period.start`) and on coerced notification payloads (delivered
+  by `MqttChannel` and `WebhookChannel`) are surfaced as zone-aware
+  `pendulum.DateTime`.
+- The wire string's UTC offset is the **source of truth** and is preserved
+  end-to-end. `Z`, `+00:00`, `-07:00`, `+05:30` round-trip exactly — no
+  normalization. See [python-oa3 README — Time and Timezones](https://github.com/grid-coordination/python-oa3#time-and-timezones)
+  for the canonical specification and round-trip table.
+- Cross-implementation parity with `clj-oa3-client` (which surfaces
+  `java.time.ZonedDateTime` under the same rule).
+
+Propagation through this client's MQTT and webhook parse paths is locked in
+by `tests/test_time_propagation.py`.
+
 ## Direct API access
 
 All `OpenADRClient` methods are available on both VenClient and BlClient via `__getattr__`:

tests/test_time_propagation.py

@@ -0,0 +1,66 @@
+"""Regression tests for pendulum.DateTime propagation through notification channels.
+
+The client itself does no datetime parsing — it forwards payloads to
+``openadr3.entities.coerce_notification`` (from python-oa3). These tests
+lock in that behavior so a regression upstream or in our parse glue would
+be caught here.
+
+The OpenADR 3 wire-offset rule: the wire string's offset is preserved
+end-to-end and is NOT normalized. ``Z``, ``+00:00``, ``-07:00``, ``+05:30``
+all round-trip exactly.
+"""
+
+import json
+
+import pendulum
+
+from openadr3_client.mqtt import _parse_payload
+from openadr3_client.webhook import _parse_webhook_payload
+
+
+def _notification_with_offset(offset: str) -> bytes:
+    return json.dumps(
+        {
+            "objectType": "PROGRAM",
+            "operation": "POST",
+            "object": {
+                "objectType": "PROGRAM",
+                "id": "p1",
+                "programName": "test",
+                "createdDateTime": f"2024-06-15T10:30:00{offset}",
+                "modificationDateTime": f"2024-06-15T10:30:00{offset}",
+            },
+        }
+    ).encode()
+
+
+class TestPendulumDateTimePropagation:
+    """Wire-offset preservation across MQTT and webhook coercion paths."""
+
+    def test_mqtt_payload_yields_pendulum_datetime(self):
+        msg = _parse_payload(_notification_with_offset("Z"), "programs/create")
+        assert isinstance(msg.object.created, pendulum.DateTime)
+        assert isinstance(msg.object.modified, pendulum.DateTime)
+
+    def test_webhook_payload_yields_pendulum_datetime(self):
+        msg = _parse_webhook_payload(_notification_with_offset("Z"), "/notifications")
+        assert isinstance(msg.object.created, pendulum.DateTime)
+
+    def test_mqtt_negative_offset_preserved(self):
+        msg = _parse_payload(_notification_with_offset("-07:00"), "programs/create")
+        assert msg.object.created.utcoffset().total_seconds() == -7 * 3600
+
+    def test_webhook_half_hour_offset_preserved(self):
+        msg = _parse_webhook_payload(_notification_with_offset("+05:30"), "/notifications")
+        assert msg.object.created.utcoffset().total_seconds() == 5.5 * 3600
+
+    def test_mqtt_z_not_normalized_to_plus_zero(self):
+        # Z and +00:00 are distinct wire forms; the parser must preserve which
+        # one came in. Round-trip the parsed DateTime back to ISO 8601 and
+        # confirm it ends with "Z".
+        msg = _parse_payload(_notification_with_offset("Z"), "programs/create")
+        assert msg.object.created.to_iso8601_string().endswith("Z")
+
+    def test_webhook_plus_zero_not_normalized_to_z(self):
+        msg = _parse_webhook_payload(_notification_with_offset("+00:00"), "/notifications")
+        assert msg.object.created.to_iso8601_string().endswith("+00:00")