fix(ingestion): compare document tails as instants, not RFC3339 strings

Email Date headers mix timezone offsets; lexicographic created_at order
could poll the wrong saga. Post-release smoke now checks out the release SHA.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jackaldenryan

.github/workflows/smoke-ingestion.yml

@@ -26,6 +26,10 @@ jobs:
         working-directory: ingestion
     steps:
       - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          # workflow_run otherwise checks out current default-branch HEAD, not
+          # the commit the Release Ingestion Package workflow ran on.
+          ref: ${{ github.event_name == 'workflow_run' && github.event.workflow_run.head_sha || github.sha }}
 
       - name: Install uv
         uses: astral-sh/setup-uv@caf0cab7a618c569241d31dcd442f54681755d39 # v3

ingestion/src/zep_ingest/result.py

@@ -3,6 +3,7 @@
 import time
 from collections.abc import Sequence
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any, Literal
 
 from zep_ingest._validation import require_int_range, require_nonnegative_number
@@ -41,6 +42,32 @@
 ]
 
 
+def _parse_created_at(value: str | None) -> datetime | None:
+    """Parse an episode ``created_at`` into a comparable UTC instant."""
+    if not value:
+        return None
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _is_later_or_equal_created_at(new_at: str | None, prior_at: str | None) -> bool:
+    """Whether ``new_at`` is the later document tail.
+
+    Missing or unparseable timestamps fall back to last-submitted-wins. Offsets
+    are compared as instants, not lexicographic RFC3339 strings.
+    """
+    new_dt = _parse_created_at(new_at)
+    prior_dt = _parse_created_at(prior_at)
+    if new_dt is None or prior_dt is None:
+        return True
+    return new_dt >= prior_dt
+
+
 def _normalize_task_status(status: str | None) -> str:
     status = status.lower() if status is not None else None
     if status is None or status in {"created", "draft", "pending", "queued"}:
@@ -178,11 +205,7 @@ def record_sequential_episode(self, episode: Episode, uuid: str) -> None:
             self._uses_document_grouping = True
             prior_at = self._document_poll_created_at.get(episode.document_id)
             new_at = episode.created_at
-            if prior_at is None or new_at is None:
-                # Missing timestamps: fall back to submission order (last wins).
-                self._document_poll_uuids[episode.document_id] = uuid
-                self._document_poll_created_at[episode.document_id] = new_at
-            elif new_at >= prior_at:
+            if _is_later_or_equal_created_at(new_at, prior_at):
                 self._document_poll_uuids[episode.document_id] = uuid
                 self._document_poll_created_at[episode.document_id] = new_at
         else:
@@ -362,10 +385,7 @@ def combine(self, *others: "IngestResult") -> "IngestResult":
                 for document_id, uuid in part._document_poll_uuids.items():
                     created_at = part._document_poll_created_at.get(document_id)
                     prior_at = combined._document_poll_created_at.get(document_id)
-                    if prior_at is None or created_at is None:
-                        combined._document_poll_uuids[document_id] = uuid
-                        combined._document_poll_created_at[document_id] = created_at
-                    elif (created_at or "") >= (prior_at or ""):
+                    if _is_later_or_equal_created_at(created_at, prior_at):
                         combined._document_poll_uuids[document_id] = uuid
                         combined._document_poll_created_at[document_id] = created_at
                 if part._plain_episode_tail is not None:

ingestion/tests/test_document_poll.py

@@ -30,3 +30,51 @@ def test_document_poll_tail_submission_order_when_created_at_missing():
     )
     result.finalize_sequential_episode_poll()
     assert result.episode_uuids == ["uuid-second"]
+
+
+def test_document_poll_tail_compares_instants_not_rfc3339_strings():
+    """Offsets that sort the wrong way lexicographically still pick the later instant."""
+    result = IngestResult(method="sequential")
+    result.record_sequential_episode(
+        Episode(
+            data="later Pacific",
+            document_id="doc-1",
+            created_at="2024-06-15T18:00:00-07:00",
+        ),
+        "uuid-later",
+    )
+    result.record_sequential_episode(
+        Episode(
+            data="earlier UTC",
+            document_id="doc-1",
+            created_at="2024-06-15T20:00:00+00:00",
+        ),
+        "uuid-earlier",
+    )
+    result.finalize_sequential_episode_poll()
+    assert result.episode_uuids == ["uuid-later"]
+
+
+def test_combine_document_poll_tail_uses_later_instant():
+    first = IngestResult(method="sequential")
+    first.record_sequential_episode(
+        Episode(
+            data="later Pacific",
+            document_id="doc-1",
+            created_at="2024-06-15T18:00:00-07:00",
+        ),
+        "uuid-later",
+    )
+    first.finalize_sequential_episode_poll()
+    second = IngestResult(method="sequential")
+    second.record_sequential_episode(
+        Episode(
+            data="earlier UTC",
+            document_id="doc-1",
+            created_at="2024-06-15T20:00:00+00:00",
+        ),
+        "uuid-earlier",
+    )
+    second.finalize_sequential_episode_poll()
+    combined = first.combine(second)
+    assert combined.episode_uuids == ["uuid-later"]