plexus-python 0.11.1__tar.gz → 0.11.2__tar.gz

{plexus_python-0.11.1 → plexus_python-0.11.2}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [0.11.2] - 2026-09-02 - Stamp run boundaries on the server's clock
+
+### Fixed
+
+- **A run's window was measured by a different clock than the points inside
+  it.** `_normalize_ts_ms` corrects generated timestamps by the offset the
+  gateway reports on connect; `start_run` / `end_run` read the local clock
+  instead. Every point taken in the final `offset` milliseconds of a run
+  therefore landed *after* `ended_at` and fell outside the window its own run
+  was evaluated over.
+
+  Measured on production: a device running 58ms behind the server sent 300
+  points and its run was judged on 284 of them. The shortfall reads exactly
+  like ingest lag, which is what it was mistaken for — a pass criterion can
+  come back green because the excursion that would have failed it was outside
+  the window by 58 milliseconds. Run boundaries now carry the same correction
+  as the telemetry. An explicitly passed `started_at` / `ended_at` is still
+  left alone.
+
 ## [0.11.1] - 2026-09-02 - Correct what the agent skills teach
 
 ### Fixed

{plexus_python-0.11.1 → plexus_python-0.11.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: plexus-python
-Version: 0.11.1
+Version: 0.11.2
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.company
 Project-URL: Documentation, https://docs.plexus.company

{plexus_python-0.11.1 → plexus_python-0.11.2}/plexus/__init__.py

@@ -23,7 +23,7 @@ from plexus.client import (
 )
 from plexus.config import RetryConfig
 
-__version__ = "0.11.1"
+__version__ = "0.11.2"
 __all__ = [
     "AuthenticationError",
     "BatchSender",

{plexus_python-0.11.1 → plexus_python-0.11.2}/plexus/client.py

@@ -60,10 +60,12 @@ if TYPE_CHECKING:  # pragma: no cover - typing only
 logger = logging.getLogger(__name__)
 
 
-def _utc_now_iso() -> str:
-    """Now as ISO-8601 with a Z offset — the shape /api/runs validates."""
-    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace(
-        "+00:00", "Z"
+def _iso_from_ms(ms: int) -> str:
+    """Epoch milliseconds as ISO-8601 with a Z offset — /api/runs validates the shape."""
+    return (
+        datetime.fromtimestamp(ms / 1000, timezone.utc)
+        .isoformat(timespec="milliseconds")
+        .replace("+00:00", "Z")
     )
 
 
@@ -350,6 +352,22 @@ class Plexus:
             return int(timestamp * 1000)
         return int(timestamp)
 
+    def _now_iso(self) -> str:
+        """Now on the SERVER's clock, as ISO-8601.
+
+        Run boundaries have to be stamped on the same clock as the telemetry
+        they bound, and `_normalize_ts_ms` corrects generated timestamps by the
+        offset the gateway reports on connect. Reading the local clock here
+        instead — which this did — leaves `ended_at` behind every point taken
+        in the final `offset` milliseconds of the run, and those points then
+        fall outside the window their own run is evaluated over.
+
+        The failure is quiet and looks like something else entirely: on a
+        device running 58ms behind the server, a 300-point run was evaluated
+        over 284 of them, and the shortfall reads exactly like ingest lag.
+        """
+        return _iso_from_ms(int(time.time() * 1000) + self._clock_offset_ms)
+
     @staticmethod
     def _infer_class(value: FlexValue) -> str:
         """Numbers are metrics; everything else (str/bool/dict/list) is an event.
@@ -584,7 +602,10 @@ class Plexus:
         Returns:
             The created run dict, including its "id".
         """
-        body: dict[str, Any] = {"name": name, "started_at": started_at or _utc_now_iso()}
+        body: dict[str, Any] = {
+            "name": name,
+            "started_at": started_at or self._now_iso(),
+        }
         if source_id is not _USE_CLIENT_SOURCE:
             body["source_id"] = source_id
         else:
@@ -664,7 +685,7 @@ class Plexus:
         return self._api(
             "PATCH",
             f"/api/runs/{run_id}",
-            {"status": status, "ended_at": ended_at or _utc_now_iso()},
+            {"status": status, "ended_at": ended_at or self._now_iso()},
         )["run"]
 
     @contextmanager

{plexus_python-0.11.1 → plexus_python-0.11.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.11.1"
+version = "0.11.2"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"

{plexus_python-0.11.1 → plexus_python-0.11.2}/tests/test_runs.py

@@ -10,6 +10,7 @@ The HTTP layer is stubbed at `_Session.request`, so no socket is opened.
 """
 
 import json
+import time
 
 import pytest
 
@@ -72,6 +73,47 @@ def test_started_at_matches_the_shape_the_route_validates():
     datetime.fromisoformat(started.replace("Z", "+00:00"))  # parses or raises
 
 
+def test_run_boundaries_are_stamped_on_the_server_clock():
+    """The window must be measured by the same clock as the points inside it.
+
+    `_normalize_ts_ms` corrects generated timestamps by the offset the gateway
+    reports on connect. Stamping run boundaries from the local clock instead
+    leaves `ended_at` behind every point taken in the final `offset`
+    milliseconds — and those points then fall outside the window their own run
+    is evaluated over. Measured on production before the fix: a 300-point run
+    on a device 58ms behind the server was judged on 284 of them, and the
+    shortfall reads exactly like ingest lag.
+    """
+    from datetime import datetime
+
+    session = _StubSession()
+    px = _client(session)
+    px._clock_offset_ms = 5_000  # device 5s behind the server
+
+    px.start_run("run")
+    px.end_run({"id": "run_1"})
+
+    def as_ms(iso: str) -> int:
+        return int(datetime.fromisoformat(iso.replace("Z", "+00:00")).timestamp() * 1000)
+
+    local_ms = int(time.time() * 1000)
+    started = as_ms(session.calls[0][2]["started_at"])
+    ended = as_ms(session.calls[1][2]["ended_at"])
+
+    # Both carry the offset, so they bound points that also carry it.
+    assert started - local_ms > 4_000
+    assert ended - local_ms > 4_000
+
+
+def test_an_explicit_boundary_is_left_alone():
+    """A caller passing its own timestamp owns it — we do not shift it."""
+    session = _StubSession()
+    px = _client(session)
+    px._clock_offset_ms = 5_000
+    px.start_run("run", started_at="2026-09-01T10:00:00.000Z")
+    assert session.calls[0][2]["started_at"] == "2026-09-01T10:00:00.000Z"
+
+
 def test_run_defaults_to_the_clients_own_source():
     session = _StubSession()
     px = _client(session)