methodic-research 0.35.0__tar.gz → 0.37.0__tar.gz

{methodic_research-0.35.0/src/methodic_research.egg-info → methodic_research-0.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodic-research
-Version: 0.35.0
+Version: 0.37.0
 Summary: Python client for the Chronicle experiment platform
 License-Expression: Apache-2.0
 Project-URL: Documentation, https://docs.methodiclabs.ai

{methodic_research-0.35.0 → methodic_research-0.37.0}/pyproject.toml

@@ -8,7 +8,7 @@ name = "methodic-research"
 # methodic-lib-publish.yml overwrites this from versions.toml at build
 # time, so the published artifact has a single source of truth. Kept
 # here for local `pip install -e conductor/`.
-version = "0.35.0"
+version = "0.37.0"
 description = "Python client for the Chronicle experiment platform"
 requires-python = ">=3.11"
 license = "Apache-2.0"

{methodic_research-0.35.0 → methodic_research-0.37.0}/src/methodic/__init__.py

@@ -18,6 +18,7 @@ from methodic.errors import (
     ServerError,
 )
 from methodic.experiments import Experiment, ExperimentsAPI
+from methodic.feed import FeedAPI
 from methodic.feedback import FeedbackAPI
 from methodic.pending import PendingAPI
 from methodic.publications import PublicationsAPI
@@ -37,6 +38,8 @@ from methodic.types import (
     ExperimentDetail,
     ExperimentListPage,
     ExperimentSummary,
+    FeedEvent,
+    FeedPage,
     GitBranch,
     GitStatus,
     GitToken,
@@ -47,6 +50,7 @@ from methodic.types import (
     SearchResponse,
     SearchResult,
     SearchScope,
+    TentativeParentLink,
     UpstreamRetraction,
     UpstreamRetractionsResponse,
     Variation as VariationData,
@@ -81,6 +85,9 @@ __all__ = [
     "ExperimentListPage",
     "ExperimentSummary",
     "ExperimentsAPI",
+    "FeedAPI",
+    "FeedEvent",
+    "FeedPage",
     "FeedbackAPI",
     "GitBranch",
     "GitStatus",
@@ -106,6 +113,7 @@ __all__ = [
     "PublicationsAPI",
     "ServerError",
     "TagsAPI",
+    "TentativeParentLink",
     "UploadTracker",
     "UpstreamRetraction",
     "UpstreamRetractionsResponse",

{methodic_research-0.35.0 → methodic_research-0.37.0}/src/methodic/chronicle.py

@@ -25,6 +25,7 @@ from methodic.datasets import DatasetsAPI
 from methodic.errata import ErrataAPI
 from methodic.errors import ChronicleConfigError
 from methodic.experiments import Experiment, ExperimentsAPI
+from methodic.feed import FeedAPI
 from methodic.feedback import FeedbackAPI
 from methodic.imports import ImportsAPI
 from methodic.me import MeAPI
@@ -274,6 +275,9 @@ class Chronicle:
         # Attention feed — the caller's actionable queue + event stream.
         self.pending = PendingAPI(self._transport, self)
         self.activity = ActivityAPI(self._transport, self)
+        # Unified event feed (event-stream.md §6): activity + needs-you + inbox
+        # + research, with an explicit per-section pointer (see FeedAPI.seen).
+        self.feed = FeedAPI(self._transport, self)
 
     @property
     def organization_id(self) -> str | None:

{methodic_research-0.35.0 → methodic_research-0.37.0}/src/methodic/experiments.py

@@ -17,6 +17,7 @@ from methodic.types import (
     GitStatus,
     GitToken,
     LineageResponse,
+    TentativeParentLink,
     UpstreamRetractionsResponse,
     resolve_organization_id,
 )
@@ -162,7 +163,28 @@ class ExperimentsAPI:
                 return
             token = page.next_page_token
 
-    def commit(self, experiment_id: str) -> dict[str, Any]:
+    def commit(
+        self,
+        experiment_id: str,
+        *,
+        tentative_links: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """Commit (lock the spec of) an experiment.
+
+        If the experiment has **tentative** parent lineage links (from being
+        created/forked off a still-``open`` parent — see
+        :meth:`tentative_links`), every one must be resolved here or commit
+        returns 409: pass ``tentative_links`` mapping each parent experiment id
+        to ``"promote"`` (make it real lineage — only valid once the parent has
+        committed) or ``"drop"`` (discard the link). Naming a parent that isn't
+        a tentative link, or omitting one that is, is rejected — there is no
+        silent default.
+        """
+        if tentative_links is not None:
+            return self._t.put(
+                f"/experiments/{experiment_id}/commit",
+                json={"tentative_links": tentative_links},
+            )
         return self._t.put(f"/experiments/{experiment_id}/commit")
 
     def conclude(
@@ -399,6 +421,33 @@ class ExperimentsAPI:
             self._t.get(f"/experiments/{experiment_id}/lineage", params=params or None)
         )
 
+    def tentative_links(self, experiment_id: str) -> list[TentativeParentLink]:
+        """The experiment's **tentative** parent lineage links.
+
+        A tentative link is created when an experiment is created/forked off a
+        parent that is still ``open`` (uncommitted). It is **excluded from
+        lineage reads** (won't show in :meth:`get` ``parent_ids`` or
+        :meth:`get_lineage`) and blocks the child's commit until resolved.
+        Returns ``[]`` for the common case (no tentative links). Resolve each
+        by :meth:`promote_lineage` (once ``promotable``) or by passing a
+        ``drop``/``promote`` disposition to :meth:`commit`.
+        """
+        resp = self._t.get(f"/experiments/{experiment_id}/tentative-links")
+        return [
+            TentativeParentLink.from_dict(t) for t in resp.get("tentative_links", [])
+        ]
+
+    def promote_lineage(self, experiment_id: str, parent_id: str) -> dict[str, Any]:
+        """Promote a tentative parent link to real (explicit) lineage.
+
+        The deliberate "yes, this fork is real lineage" action: the parent then
+        appears in :meth:`get` ``parent_ids`` and the lineage DAG. Requires the
+        parent to have **committed** (else 409); a tentative link off a still-
+        ``open`` parent is not yet promotable. Idempotent — re-promoting an
+        already-explicit link succeeds.
+        """
+        return self._t.post(f"/experiments/{experiment_id}/lineage/{parent_id}/promote")
+
     def git_status(self, experiment_id: str) -> GitStatus:
         """Current git-integration state for the experiment.
 
@@ -537,8 +586,11 @@ class Experiment:
         """Mint a 1-hour install token scoped to this experiment's repo."""
         return self._chronicle.experiments.mint_git_token(self.id)
 
-    def commit(self) -> Experiment:
-        self._chronicle.experiments.commit(self.id)
+    def commit(self, *, tentative_links: dict[str, str] | None = None) -> Experiment:
+        """Commit (lock the spec). Pass ``tentative_links`` (parent id →
+        ``"promote"``/``"drop"``) to resolve any tentative parent links, which
+        otherwise block commit. See :meth:`ExperimentsAPI.commit`."""
+        self._chronicle.experiments.commit(self.id, tentative_links=tentative_links)
         self._detail = None
         return self
 
@@ -651,6 +703,16 @@ class Experiment:
             self.id, direction=direction, depth=depth
         )
 
+    def tentative_links(self) -> list[TentativeParentLink]:
+        """This experiment's tentative parent lineage links (empty for the
+        common case). See :meth:`ExperimentsAPI.tentative_links`."""
+        return self._chronicle.experiments.tentative_links(self.id)
+
+    def promote_lineage(self, parent_id: str) -> dict[str, Any]:
+        """Promote a tentative parent link to real lineage (parent must have
+        committed). See :meth:`ExperimentsAPI.promote_lineage`."""
+        return self._chronicle.experiments.promote_lineage(self.id, parent_id)
+
     def get_upstream_retractions(
         self,
         *,

methodic_research-0.37.0/src/methodic/feed.py

@@ -0,0 +1,170 @@
+"""Feed namespace — the caller's unified event feed.
+
+Wraps ``GET /v1/feed`` (the JSON page) and ``POST /v1/feed/seen`` (the
+per-section cursor) — the unified event stream that subsumes activity, the
+actionable "needs you" items (blocked / report_approval / invites), new
+reports, and research recommendations (event-stream.md §6).
+
+Two cross-cutting lenses are preset filters, not separate calls:
+
+- **needs-you** — ``list(actionable=True, open=True)``: blocked agents +
+  approvals + invites still awaiting you.
+- **inbox** — ``list(recipient="me")``: items addressed to you specifically.
+
+The list is ACL-bounded server-side (the same enumeration authorization the
+experiment listing uses). Pagination is a keyset on ``seq``: the JSON body is a
+bare array, the server signals more via ``X-Has-More`` and this read's
+unseen/open count via ``X-Unseen-Count``, and the next (older) page is fetched
+with ``before=<seq>``.
+
+**Pointer contract (event-stream.md §4).** Reading never advances your pointer.
+After you have *durably processed* the events you read, advance it explicitly
+with :meth:`seen` — at-least-once: a crash between read and ack re-delivers,
+never drops. (The web UI advances automatically on view; an agent must ack
+deliberately.)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any, Iterator
+
+from methodic.pending import _has_more
+from methodic.transport import Transport
+from methodic.types import FeedPage
+
+if TYPE_CHECKING:
+    from methodic.chronicle import Chronicle
+
+logger = logging.getLogger(__name__)
+
+
+def _unseen_count(headers: Any) -> int:
+    """Read the ``X-Unseen-Count`` response header as an int (default 0)."""
+    try:
+        return int(str(headers.get("X-Unseen-Count", "0")).strip() or 0)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _bool_param(value: bool) -> str:
+    """Serialize a bool for the query string as serde expects (``true``/``false``)."""
+    return "true" if value else "false"
+
+
+class FeedAPI:
+    """The caller's unified event feed (activity + needs-you + inbox + research)."""
+
+    def __init__(self, transport: Transport, chronicle: Chronicle) -> None:
+        self._t = transport
+        self._chronicle = chronicle
+
+    def list(
+        self,
+        *,
+        category: str | list[str] | None = None,
+        actionable: bool | None = None,
+        open: bool | None = None,
+        recipient: str | None = None,
+        experiment: str | None = None,
+        kind: str | None = None,
+        severity: str | None = None,
+        after_seq: int | None = None,
+        before: int | None = None,
+        limit: int | None = None,
+        order: str | None = None,
+    ) -> FeedPage:
+        """One page of feed events, newest-first (or ``score``-first for research).
+
+        Filters mirror ``GET /v1/feed``: ``category`` (a string or list of
+        categories), the ``actionable`` / ``open`` lens, ``recipient="me"`` for
+        the inbox, plus ``experiment`` / ``kind`` / ``severity``. Page with
+        ``limit`` + ``before=<seq>`` (older), or poll forward with
+        ``after_seq=<seq>``. ``order`` is ``"seq"`` (default) or ``"score"``.
+
+        The result carries ``unseen_count`` (this section's unseen/open badge)
+        and a ``next_page_token`` (the last event's ``seq``) when more remain;
+        pass it back as ``before``, or use :meth:`iter` to walk every page.
+        Reading does **not** advance your pointer — call :meth:`seen` after you
+        act.
+        """
+        params: dict[str, Any] = {}
+        if category is not None:
+            params["category"] = (
+                ",".join(category) if isinstance(category, list) else category
+            )
+        if actionable is not None:
+            params["actionable"] = _bool_param(actionable)
+        if open is not None:
+            params["open"] = _bool_param(open)
+        if recipient is not None:
+            params["recipient"] = recipient
+        if experiment is not None:
+            params["experiment"] = experiment
+        if kind is not None:
+            params["kind"] = kind
+        if severity is not None:
+            params["severity"] = severity
+        if after_seq is not None:
+            params["after_seq"] = after_seq
+        if before is not None:
+            params["before"] = before
+        if limit is not None:
+            params["limit"] = limit
+        if order is not None:
+            params["order"] = order
+        rows, headers = self._t.get_with_headers("/feed", params=params or None)
+        return FeedPage.from_list(
+            rows, has_more=_has_more(headers), unseen_count=_unseen_count(headers)
+        )
+
+    def iter(
+        self,
+        *,
+        category: str | list[str] | None = None,
+        actionable: bool | None = None,
+        open: bool | None = None,
+        recipient: str | None = None,
+        experiment: str | None = None,
+        kind: str | None = None,
+        severity: str | None = None,
+        order: str | None = None,
+        limit: int | None = None,
+    ) -> Iterator[Any]:
+        """Yield every matching feed event, paging server-side as needed.
+
+        Walks oldest-ward via the ``before=<seq>`` cursor. Forward polling
+        (``after_seq``) is a single-call concern, so it is intentionally not a
+        parameter here — use :meth:`list` for incremental tailing.
+        """
+        token: int | None = None
+        while True:
+            page = self.list(
+                category=category,
+                actionable=actionable,
+                open=open,
+                recipient=recipient,
+                experiment=experiment,
+                kind=kind,
+                severity=severity,
+                before=token,
+                limit=limit,
+                order=order,
+            )
+            yield from page.results
+            if page.next_page_token is None:
+                return
+            token = int(page.next_page_token)
+
+    def seen(self, *, section: str, through_seq: int) -> None:
+        """Advance your pointer for one section to a seq you have FINISHED handling.
+
+        ``section`` is ``blocked`` / ``approvals`` / ``research`` / ``passive``
+        (see each event's section); ``through_seq`` is the highest event ``seq``
+        you've durably processed. Monotonic — a lower seq is a no-op. Call this
+        only *after* acting on the events (at-least-once); reading never advances
+        the pointer.
+        """
+        self._t.post(
+            "/feed/seen", json={"section": section, "through_seq": through_seq}
+        )

{methodic_research-0.35.0 → methodic_research-0.37.0}/src/methodic/types.py

@@ -228,17 +228,55 @@ class UpstreamRetractionsResponse:
         )
 
 
+@dataclass
+class TentativeParentLink:
+    """One **tentative** parent lineage link — recorded by creating/forking an
+    experiment whose parent was still ``open`` (uncommitted) at the time.
+
+    A tentative link is **excluded from lineage reads** (it does not appear in
+    ``ExperimentDetail.parent_ids`` or ``experiments.get_lineage``) and the
+    child **cannot commit** until every one is resolved — promoted to real
+    lineage (only once ``promotable``) or dropped. Surfaced by
+    ``CreateExperimentResponse.tentative_parents`` and
+    ``experiments.tentative_links(id)``.
+    """
+
+    parent_id: str
+    parent_state: str
+    promotable: bool
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> TentativeParentLink:
+        return _from_dict(cls, data)
+
+
 @dataclass
 class CreateExperimentResponse:
-    """`POST /experiments` response: the new experiment plus the always-created variation 0 / run 0."""
+    """`POST /experiments` response: the new experiment plus the always-created variation 0 / run 0.
+
+    ``tentative_parents`` is non-empty only when the experiment was created
+    with a parent that was still ``open`` — see :class:`TentativeParentLink`.
+    Empty for the common (no-parent / committed-parent) case.
+    """
 
     experiment_id: str
     variation: int
     run: int
+    tentative_parents: list[TentativeParentLink] = dataclasses.field(
+        default_factory=list
+    )
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> CreateExperimentResponse:
-        return _from_dict(cls, data)
+        return cls(
+            experiment_id=data["experiment_id"],
+            variation=data["variation"],
+            run=data["run"],
+            tentative_parents=[
+                TentativeParentLink.from_dict(t)
+                for t in data.get("tentative_parents", [])
+            ],
+        )
 
 
 @dataclass
@@ -425,7 +463,7 @@ class ExperimentListPage:
         )
 
 
-# ── Attention feed (pending + activity) ───────────────────────────────────
+# ── Attention feed (pending + activity + unified feed) ─────────────────────
 
 
 @dataclass
@@ -545,6 +583,78 @@ class ActivityPage:
         return cls(results=results, next_page_token=next_token)
 
 
+@dataclass
+class FeedEvent:
+    """One row of the unified event feed from `GET /v1/feed` (event-stream.md).
+
+    The feed unifies activity, the actionable "needs you" items (``blocked`` /
+    ``report_approval`` / invites), new reports, and research recommendations
+    under one stream. `seq` is the global monotonic cursor key — the value you
+    pass to :meth:`FeedAPI.seen` (as ``through_seq``) and to ``before`` /
+    ``after_seq`` for paging. `category` is the granular content type and rolls
+    up into a `section` (``blocked`` / ``approvals`` / ``research`` /
+    ``passive``) — the unit the cursor is keyed on. `actionable` items stay open
+    until `resolved_at` is set. `recipient_principal_id` is set when the event is
+    addressed to a specific principal (the inbox lens); broadcast/resource items
+    use `audience` + `experiment_id` instead. `payload` is the event-specific
+    "what changed" blob.
+    """
+
+    seq: int
+    id: str
+    category: str
+    kind: str
+    created_at: str
+    via: str
+    audience: str
+    actionable: bool
+    severity: str
+    payload: dict[str, Any]
+    actor_subject: str | None = None
+    resource_type: str | None = None
+    resource_id: str | None = None
+    experiment_id: str | None = None
+    recipient_principal_id: str | None = None
+    resolved_at: str | None = None
+    resolved_by: str | None = None
+    resolving_seq: int | None = None
+    score: float | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> FeedEvent:
+        return _from_dict(cls, data)
+
+
+@dataclass
+class FeedPage:
+    """One page of `feed.list` results plus the section unseen count + a cursor.
+
+    The server returns a **bare array** and carries page metadata in headers:
+    ``X-Has-More`` (it over-fetches one row to decide) and ``X-Unseen-Count``
+    (this read's unseen/open count for the queried section). The SDK reads both;
+    when more remain it builds ``next_page_token`` from the last event's ``seq``
+    — the ``?before`` cursor the server consumes for the next (older) page.
+    ``next_page_token`` is ``None`` on the last page. Use :meth:`FeedAPI.iter` to
+    walk every page.
+    """
+
+    results: list[FeedEvent]
+    unseen_count: int = 0
+    next_page_token: str | None = None
+
+    @classmethod
+    def from_list(
+        cls, rows: Any, *, has_more: bool, unseen_count: int = 0
+    ) -> FeedPage:
+        results = [FeedEvent.from_dict(r) for r in (rows or [])]
+        next_token = None
+        if has_more and results:
+            next_token = str(results[-1].seq)
+        return cls(
+            results=results, unseen_count=unseen_count, next_page_token=next_token
+        )
+
+
 @dataclass
 class BulkApproveResult:
     """Per-asset outcome within a `BulkApproveResponse`.

{methodic_research-0.35.0 → methodic_research-0.37.0/src/methodic_research.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: methodic-research
-Version: 0.35.0
+Version: 0.37.0
 Summary: Python client for the Chronicle experiment platform
 License-Expression: Apache-2.0
 Project-URL: Documentation, https://docs.methodiclabs.ai

{methodic_research-0.35.0 → methodic_research-0.37.0}/src/methodic_research.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ src/methodic/datasets.py
 src/methodic/errata.py
 src/methodic/errors.py
 src/methodic/experiments.py
+src/methodic/feed.py
 src/methodic/feedback.py
 src/methodic/imports.py
 src/methodic/me.py
@@ -42,6 +43,7 @@ tests/test_config.py
 tests/test_datasets.py
 tests/test_distill.py
 tests/test_experiments.py
+tests/test_feed.py
 tests/test_feedback.py
 tests/test_imports.py
 tests/test_pending.py

{methodic_research-0.35.0 → methodic_research-0.37.0}/tests/test_experiments.py

@@ -390,6 +390,102 @@ def test_upstream_retractions_full_chain(requests_mock):
     assert resp.retractions == []
 
 
+# --- Tentative lineage links (fork of an open parent) ---
+
+def test_create_surfaces_tentative_parents(requests_mock):
+    requests_mock.post(
+        f"{BASE}/v1/experiments",
+        json={
+            "experiment_id": EXP,
+            "variation": 0,
+            "run": 0,
+            "tentative_parents": [
+                {"parent_id": "p-open", "parent_state": "open", "promotable": False}
+            ],
+        },
+    )
+
+    exp = _chronicle().experiments.create(
+        hypothesis_summary="builds on p-open",
+        config_yaml="model: {}\n",
+        parent_experiment_ids=["p-open"],
+    )
+
+    links = exp._create_response.tentative_parents
+    assert len(links) == 1
+    assert links[0].parent_id == "p-open"
+    assert links[0].parent_state == "open"
+    assert links[0].promotable is False
+
+
+def test_tentative_links_lists_pending_links(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}/tentative-links",
+        json={
+            "experiment_id": EXP,
+            "tentative_links": [
+                {"parent_id": "p1", "parent_state": "committed", "promotable": True}
+            ],
+        },
+    )
+
+    links = _chronicle().experiments.tentative_links(EXP)
+
+    assert requests_mock.last_request.path == f"/v1/experiments/{EXP}/tentative-links"
+    assert len(links) == 1
+    assert links[0].parent_id == "p1"
+    assert links[0].promotable is True
+
+
+def test_promote_lineage_posts_to_promote_route(requests_mock):
+    requests_mock.post(
+        f"{BASE}/v1/experiments/{EXP}/lineage/p1/promote",
+        json={"experiment_id": EXP, "parent_id": "p1", "promoted": True},
+    )
+
+    resp = _chronicle().experiments.promote_lineage(EXP, "p1")
+
+    assert requests_mock.last_request.path == f"/v1/experiments/{EXP}/lineage/p1/promote"
+    assert resp["promoted"] is True
+
+
+def test_commit_sends_tentative_link_resolutions(requests_mock):
+    requests_mock.put(f"{BASE}/v1/experiments/{EXP}/commit", json={"committed": True})
+
+    _chronicle().experiments.commit(
+        EXP, tentative_links={"p1": "promote", "p2": "drop"}
+    )
+
+    body = requests_mock.last_request.json()
+    assert body["tentative_links"] == {"p1": "promote", "p2": "drop"}
+
+
+def test_commit_without_resolutions_sends_no_body(requests_mock):
+    requests_mock.put(f"{BASE}/v1/experiments/{EXP}/commit", json={"committed": True})
+
+    _chronicle().experiments.commit(EXP)
+
+    assert requests_mock.last_request.body is None
+
+
+def test_handle_promote_lineage_proxies(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/experiments/{EXP}",
+        json=_detail_payload(),
+    )
+    requests_mock.post(
+        f"{BASE}/v1/experiments/{EXP}/lineage/p1/promote",
+        json={"experiment_id": EXP, "parent_id": "p1", "promoted": True},
+    )
+
+    exp = _chronicle().experiments.get(EXP)
+    from methodic import Experiment
+
+    handle = Experiment(_chronicle(), EXP, _detail=exp)
+    resp = handle.promote_lineage("p1")
+    assert resp["promoted"] is True
+
+
 # --- Variations sub-namespace via handle ---
 
 def test_variations_create_through_handle(requests_mock):

methodic_research-0.37.0/tests/test_feed.py

@@ -0,0 +1,135 @@
+"""Tests for the Feed namespace (the caller's unified event feed)."""
+
+from methodic import Chronicle
+
+BASE = "http://localhost:8080"
+
+
+def _chronicle():
+    return Chronicle(server_url=BASE, api_key="sk_user_test")
+
+
+def _event(**overrides):
+    base = {
+        "seq": 42,
+        "id": "11111111-1111-1111-1111-111111111111",
+        "category": "activity",
+        "kind": "run.succeeded",
+        "created_at": "2026-06-02T12:00:00Z",
+        "via": "direct",
+        "audience": "experiment_readers",
+        "actionable": False,
+        "severity": "info",
+        "payload": {"foo": "bar"},
+        "experiment_id": "exp-1",
+        "recipient_principal_id": "auth0|alice",
+    }
+    base.update(overrides)
+    return base
+
+
+def test_list_returns_typed_events_and_unseen_count(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[_event()],
+        headers={"X-Has-More": "false", "X-Unseen-Count": "3"},
+    )
+
+    page = _chronicle().feed.list(category="activity")
+
+    assert page.next_page_token is None
+    assert page.unseen_count == 3
+    assert len(page.results) == 1
+    ev = page.results[0]
+    assert ev.seq == 42
+    assert ev.category == "activity"
+    assert ev.kind == "run.succeeded"
+    assert ev.payload == {"foo": "bar"}
+    assert ev.recipient_principal_id == "auth0|alice"
+
+
+def test_list_omits_optional_fields(requests_mock):
+    """Optional resolution/score fields absent on the wire → None."""
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[_event()],
+        headers={"X-Has-More": "false"},
+    )
+
+    ev = _chronicle().feed.list().results[0]
+    assert ev.resolved_at is None
+    assert ev.resolving_seq is None
+    assert ev.score is None
+    # Missing X-Unseen-Count header defaults to 0.
+    assert _chronicle().feed.list().unseen_count == 0
+
+
+def test_list_builds_cursor_from_seq(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[_event(seq=42)],
+        headers={"X-Has-More": "true", "X-Unseen-Count": "1"},
+    )
+
+    page = _chronicle().feed.list()
+    assert page.next_page_token == "42"
+
+
+def test_list_threads_filters_and_lenses(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        json=[],
+        headers={"X-Has-More": "false"},
+    )
+
+    _chronicle().feed.list(
+        category=["report_approval", "experiment_invite"],
+        actionable=True,
+        open=True,
+        recipient="me",
+        experiment="exp-1",
+        kind="invite.received",
+        severity="warning",
+        after_seq=10,
+        limit=25,
+        order="score",
+    )
+
+    qs = requests_mock.last_request.qs
+    assert qs["category"] == ["report_approval,experiment_invite"]
+    assert qs["actionable"] == ["true"]
+    assert qs["open"] == ["true"]
+    assert qs["recipient"] == ["me"]
+    assert qs["experiment"] == ["exp-1"]
+    assert qs["kind"] == ["invite.received"]
+    assert qs["severity"] == ["warning"]
+    assert qs["after_seq"] == ["10"]
+    assert qs["limit"] == ["25"]
+    assert qs["order"] == ["score"]
+
+
+def test_seen_posts_section_and_through_seq(requests_mock):
+    requests_mock.post(f"{BASE}/v1/feed/seen", status_code=204)
+
+    _chronicle().feed.seen(section="passive", through_seq=42)
+
+    assert requests_mock.last_request.json() == {
+        "section": "passive",
+        "through_seq": 42,
+    }
+
+
+def test_iter_walks_before_cursor(requests_mock):
+    requests_mock.get(
+        f"{BASE}/v1/feed",
+        [
+            {"json": [_event(seq=42)], "headers": {"X-Has-More": "true"}},
+            {"json": [_event(seq=40)], "headers": {"X-Has-More": "false"}},
+        ],
+    )
+
+    seqs = [e.seq for e in _chronicle().feed.iter()]
+    assert seqs == [42, 40]
+    assert requests_mock.call_count == 2
+    second = requests_mock.request_history[1]
+    assert second.qs["before"] == ["42"]