Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
33.4 KB
Raw Blame
"""Public Time and Timeline API, including atomic Temporal Claim writes."""

from __future__ import annotations

import json
import sqlite3
from contextlib import closing

import pytest
from fastapi import HTTPException

from azimut.api.cases import timeline
from azimut.sqlite_backend import SQLITE_SCHEMA
from azimut.workspace import Case


def _case(client, name="Timeline"):
    return client.post("/api/cases", json={"name": name}).json()["id"]


def _entity(client, case_id, type_, label, attrs=None):
    response = client.post(
        f"/api/cases/{case_id}/entities",
        json={"type": type_, "label": label, "attrs": attrs or {}},
    )
    assert response.status_code == 200, response.text
    return response.json()


def test_atomic_create_returns_a_normalized_claim_and_connectors(client):
    case_id = _case(client)
    subject = _entity(client, case_id, "ip", "203.0.113.42")
    source = _entity(client, case_id, "bookmark", "Access log", {"url": "https://x.test"})

    created = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={
            "statement": "This address appeared in the access log",
            "when": "2026-08-11T10:32:14Z",
            "time_role": "observed",
            "confidence": "probable",
            "about": [subject["id"]],
            "cites": [source["id"]],
        },
    )

    assert created.status_code == 200, created.text
    body = created.json()
    assert body["entity"]["attrs"]["when"] == "2026-08-11T10:32:14Z"
    assert {(link["type"], link["to"]) for link in body["links"]} == {
        ("about", subject["id"]),
        ("cites", source["id"]),
    }
    assert body["temporal"]["earliest"] == "2026-08-11T10:32:14.000000Z"
    assert body["temporal"]["latest"] == "2026-08-11T10:32:15.000000Z"
    assert body["temporal"]["subjects"] == [subject["id"]]
    assert body["temporal"]["sources"] == [source["id"]]


def test_a_bad_connector_rolls_back_the_whole_claim(client):
    case_id = _case(client)
    person = _entity(client, case_id, "person", "Witness")

    refused = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Invalid evidence", "cites": [person["id"]]},
    )

    assert refused.status_code == 400
    entities = Case.open(case_id).list_entities()
    assert [entity["type"] for entity in entities] == ["person"]


def test_a_line_creates_the_subjects_it_names_with_its_claim(client):
    case_id = _case(client)
    place = _entity(client, case_id, "place", "Crossroads", {"lat": 49.9, "lon": 36.2})

    created = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={
            "statement": "4th brigade seen at Crossroads",
            "at": [place["id"]],
            "create": [
                {"slot": "about", "type": "organization", "label": " 4th brigade "},
                {"slot": "about", "type": "account", "label": "@spotter"},
            ],
        },
    )

    assert created.status_code == 200, created.text
    body = created.json()
    made = body["created"]
    assert [(entry["type"], entry["label"], entry["slot"]) for entry in made] == [
        ("organization", "4th brigade", "about"),
        ("account", "@spotter", "about"),
    ]
    assert {(link["type"], link["to"]) for link in body["links"]} == {
        ("at", place["id"]),
        ("about", made[0]["id"]),
        ("about", made[1]["id"]),
    }
    case = Case.open(case_id)
    organization = case.get_entity(made[0]["id"])
    assert organization["provenance"]["by"] == "user"
    assert organization["provenance"]["status"] == "confirmed"

    # Undo is the grouped delete: the Claim and what it created, as one trash group.
    undone = client.post(
        f"/api/cases/{case_id}/entities/delete",
        json={"ids": [body["entity"]["id"], *(entry["id"] for entry in made)]},
    )
    assert undone.status_code == 200, undone.text
    assert sorted(entity["type"] for entity in case.list_entities()) == ["place"]
    restored = client.post(f"/api/cases/{case_id}/trash/{undone.json()['trash']}/restore")
    assert restored.status_code == 200, restored.text
    assert sorted(entity["type"] for entity in case.list_entities()) == [
        "account", "claim", "organization", "place",
    ]


@pytest.mark.parametrize(
    ("entry", "reason"),
    [
        ({"slot": "about", "type": "place", "label": "Somewhere"}, "cannot be a 'place'"),
        ({"slot": "about", "type": "media", "label": "clip.mp4"}, "cannot be a 'media'"),
        ({"slot": "about", "type": "claim", "label": "Another"}, "cannot be a 'claim'"),
        ({"slot": "about", "type": "unheard-of", "label": "X"}, "cannot be a 'unheard-of'"),
        ({"slot": "about", "type": "person", "label": "   "}, "needs a name"),
        # A person is not evidence: the vocabulary refuses the seat, after the
        # subject was written, and the whole line goes back.
        ({"slot": "cites", "type": "person", "label": "Witness"}, ""),
    ],
)
def test_a_new_subject_the_line_cannot_create_leaves_nothing(client, entry, reason):
    case_id = _case(client)

    refused = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Something seen", "create": [entry]},
    )

    assert refused.status_code == 400, refused.text
    assert reason in refused.json()["detail"]
    assert Case.open(case_id).list_entities() == []


def test_a_line_names_at_most_ten_new_subjects(client):
    case_id = _case(client)
    entries = [{"slot": "about", "type": "person", "label": f"P{n}"} for n in range(11)]

    refused = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Crowd", "create": entries},
    )

    assert refused.status_code == 422
    assert Case.open(case_id).list_entities() == []


def test_a_claim_without_new_subjects_still_posts_the_old_body(client):
    case_id = _case(client)

    created = client.post(
        f"/api/cases/{case_id}/timeline/claims", json={"statement": "Plain"}
    )

    assert created.status_code == 200, created.text
    assert created.json()["created"] == []


def test_subsecond_bounds_sort_filter_and_measure_the_extent_chronologically(client):
    case_id = _case(client, "Subsecond order")
    for statement, when in (
        ("Whole second", "2026-08-11T10:32:14Z"),
        ("One half", "2026-08-11T10:32:14.5Z"),
        ("Five decimal places", "2026-08-11T10:32:14.50001Z"),
    ):
        response = client.post(
            f"/api/cases/{case_id}/timeline/claims",
            json={"statement": statement, "when": when},
        )
        assert response.status_code == 200, response.text

    page = client.get(
        f"/api/cases/{case_id}/timeline",
        params={"category": "statement", "include_undated": "false"},
    ).json()

    assert [item["label"] for item in page["items"]] == [
        "Whole second",
        "One half",
        "Five decimal places",
    ]
    assert [item["earliest"] for item in page["items"]] == [
        "2026-08-11T10:32:14.000000Z",
        "2026-08-11T10:32:14.500000Z",
        "2026-08-11T10:32:14.500010Z",
    ]
    assert page["extent"] == {
        "from": "2026-08-11T10:32:14.000000Z",
        "to": "2026-08-11T10:32:15.000000Z",
    }

    narrow = client.get(
        f"/api/cases/{case_id}/timeline",
        params={
            "from": "2026-08-11T10:32:14.500005Z",
            "to": "2026-08-11T10:32:14.500009Z",
            "category": "statement",
            "include_undated": "false",
        },
    ).json()
    assert [item["label"] for item in narrow["items"]] == [
        "Whole second",
        "One half",
    ]


def test_timeline_filters_intersections_categories_entities_and_undated(client):
    case_id = _case(client)
    subject = _entity(client, case_id, "person", "Witness")
    other = _entity(client, case_id, "person", "Other")
    for statement, when, about in (
        ("During August", "2026-08/2026-09", subject["id"]),
        ("One day elsewhere", "2026-07-01", other["id"]),
        ("Not dated yet", None, subject["id"]),
    ):
        payload = {"statement": statement, "about": [about]}
        if when:
            payload["when"] = when
        response = client.post(f"/api/cases/{case_id}/timeline/claims", json=payload)
        assert response.status_code == 200, response.text

    page = client.get(
        f"/api/cases/{case_id}/timeline",
        params={
            "from": "2026-08-15",
            "to": "2026-08-20",
            "entity": subject["id"],
            "category": "statement",
            "include_undated": "true",
            "bucket": "month",
        },
    )

    assert page.status_code == 200, page.text
    body = page.json()
    assert [item["label"] for item in body["items"]] == ["During August", "Not dated yet"]
    assert body["undated"] == 1
    assert body["unplaced"] == 0
    # A bucket carries the span of its own entries beside the count: the overview
    # opens a clicked bar onto what it holds rather than onto the whole month.
    assert body["buckets"] == [
        {
            "start": "2026-08",
            "count": 1,
            "categories": {"statement": 1},
            "first": "2026-08-01T00:00:00.000000Z",
            "last": "2026-10-01T00:00:00.000000Z",
        }
    ]
    assert body["window"] == {
        "from": "2026-08-15T00:00:00.000000Z",
        "to": "2026-08-21T00:00:00.000000Z",
    }
    assert body["extent"] == {
        "from": "2026-08-01T00:00:00.000000Z",
        "to": "2026-10-01T00:00:00.000000Z",
    }


def test_local_time_is_counted_as_unplaced_instead_of_undated(client):
    case_id = _case(client)
    created = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Local observation", "when": "2021-04-24T14:52:29"},
    )
    assert created.status_code == 200, created.text

    body = client.get(
        f"/api/cases/{case_id}/timeline",
        params={"category": "statement", "include_undated": "true"},
    ).json()
    assert body["undated"] == 0
    assert body["unplaced"] == 1
    assert body["items"][0]["raw"] == "2021-04-24T14:52:29"
    assert body["items"][0]["zone"] == "local"


def test_a_day_stated_in_a_zone_is_that_zones_day_on_the_axis(client):
    """The 12th in Tokyo ends at 15:00 UTC, so a window closing at 16:00 UTC on
    the 12th holds all of it; read as UTC's day it would spill past the window."""
    case_id = _case(client)
    created = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Filmed", "when": "2024-03-12", "when_zone": "Asia/Tokyo"},
    )
    assert created.status_code == 200, created.text
    row = created.json()["temporal"]
    assert (row["earliest"], row["latest"], row["tz"]) == (
        "2024-03-11T15:00:00.000000Z", "2024-03-12T15:00:00.000000Z", "Asia/Tokyo",
    )

    local = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Clock", "when": "2024-03-12T09:00:00", "when_zone": "Asia/Tokyo"},
    )
    assert local.json()["temporal"]["earliest"] == "2024-03-12T00:00:00.000000Z"
    assert local.json()["temporal"]["zone"] == "named"


def test_a_time_keeps_the_clock_it_was_picked_on_beside_its_offset(client):
    """A time is written with the offset its zone keeps then, and the row still
    names the zone, so the Timeline says Kyiv rather than a bare +03:00."""
    case_id = _case(client)
    created = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Strike", "when": "2024-07-12T14:30:00+03:00", "when_zone": "Europe/Kyiv"},
    )
    assert created.status_code == 200, created.text
    row = created.json()["temporal"]
    assert (row["earliest"], row["zone"], row["tz"]) == (
        "2024-07-12T11:30:00.000000Z", "offset", "Europe/Kyiv",
    )


def test_a_zone_leaves_with_the_date_it_read(client):
    case_id = _case(client)
    claim_id = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Filmed", "when": "2024-03-12", "when_zone": "Europe/Kyiv"},
    ).json()["entity"]["id"]

    # Editing the date alone keeps the zone it was stated in.
    moved = client.patch(
        f"/api/cases/{case_id}/timeline/claims/{claim_id}", json={"when": "2024-03-13"}
    )
    assert moved.json()["entity"]["attrs"]["when_zone"] == "Europe/Kyiv"
    assert moved.json()["temporal"]["earliest"] == "2024-03-12T22:00:00.000000Z"

    cleared = client.patch(
        f"/api/cases/{case_id}/timeline/claims/{claim_id}", json={"when": None}
    )
    assert "when_zone" not in cleared.json()["entity"]["attrs"]

    refused = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Nowhere", "when": "2024-03-12", "when_zone": "Mars/Olympus"},
    )
    assert refused.status_code == 400


def test_timestamp_window_uses_the_given_second_as_its_upper_boundary(client):
    case_id = _case(client)
    for second in (0, 1):
        response = client.post(
            f"/api/cases/{case_id}/timeline/claims",
            json={
                "statement": f"Observation {second}",
                "when": f"2026-08-12T10:00:{second:02d}Z",
            },
        )
        assert response.status_code == 200, response.text

    response = client.get(
        f"/api/cases/{case_id}/timeline",
        params={
            "category": "statement",
            "from": "2026-08-12T10:00:00Z",
            "to": "2026-08-12T10:00:01Z",
        },
    )

    assert response.status_code == 200, response.text
    assert [item["label"] for item in response.json()["items"]] == ["Observation 0"]
    assert response.json()["window"]["to"] == "2026-08-12T10:00:01.000000Z"


def test_a_spread_read_reaches_the_far_end_of_a_lopsided_window(client):
    case_id = _case(client)
    for index in range(30):
        _entity(client, case_id, "claim", f"Jan {index:02d}", {"when": f"2026-01-{index % 28 + 1:02d}"})
    for index in range(5):
        _entity(client, case_id, "claim", f"Jul {index:02d}", {"when": f"2026-07-{index + 1:02d}"})

    params = {"category": "statement", "limit": 20}
    front = client.get(f"/api/cases/{case_id}/timeline", params=params).json()
    spread = client.get(
        f"/api/cases/{case_id}/timeline", params={**params, "spread": "true"}
    ).json()

    assert front["total"] == spread["total"] == 35
    assert {item["earliest"][:7] for item in front["items"]} == {"2026-01"}
    assert {item["earliest"][:7] for item in spread["items"]} == {"2026-01", "2026-07"}

    seen = list(spread["items"])
    cursor = spread["next_cursor"]
    while cursor:
        page = client.get(
            f"/api/cases/{case_id}/timeline",
            params={**params, "spread": "true", "cursor": cursor},
        ).json()
        seen.extend(page["items"])
        cursor = page["next_cursor"]
    assert len({item["id"] for item in seen}) == 35


def test_a_time_assessment_about_a_claim_explains_the_single_date_rule(client):
    case_id = _case(client)
    original = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "A vehicle crossed the gate", "when": "2026-08-12"},
    ).json()["entity"]

    response = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={
            "statement": "The crossing occurred later",
            "when": "2026-08-13",
            "about": [original["id"]],
        },
    )

    assert response.status_code == 400
    assert response.json()["detail"] == (
        "A Claim has one date or range. Edit its date, or create a separate Claim."
    )


def test_timeline_uses_keyset_pagination(client):
    case_id = _case(client)
    for day in range(1, 6):
        response = client.post(
            f"/api/cases/{case_id}/timeline/claims",
            json={"statement": f"Event {day}", "when": f"2026-08-{day:02d}"},
        )
        assert response.status_code == 200, response.text

    first = client.get(
        f"/api/cases/{case_id}/timeline",
        params={"category": "statement", "limit": 2},
    ).json()
    second = client.get(
        f"/api/cases/{case_id}/timeline",
        params={"category": "statement", "limit": 2, "cursor": first["next_cursor"]},
    ).json()

    assert [item["label"] for item in first["items"]] == ["Event 1", "Event 2"]
    assert [item["label"] for item in second["items"]] == ["Event 3", "Event 4"]
    assert first["total"] == 5


def test_update_delete_undo_and_rebuild_keep_the_projection_in_step(client):
    case_id = _case(client)
    subject = _entity(client, case_id, "person", "Witness")
    created = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "First reading", "when": "2026-08", "about": [subject["id"]]},
    ).json()
    claim_id = created["entity"]["id"]

    updated = client.patch(
        f"/api/cases/{case_id}/timeline/claims/{claim_id}",
        json={"statement": "Corrected reading", "when": "2026-09?", "about": []},
    )
    assert updated.status_code == 200, updated.text
    assert updated.json()["temporal"]["raw"] == "2026-09?"
    assert updated.json()["temporal"]["subjects"] == []

    case = Case.open(case_id)
    before = case.timeline_page(categories=["statement"])
    assert case.rebuild_temporal_projection() >= before["total"]
    assert case.timeline_page(categories=["statement"]) == before

    deleted = client.delete(f"/api/cases/{case_id}/timeline/claims/{claim_id}").json()
    assert case.timeline_page(categories=["statement"])["total"] == 0
    restored = client.post(f"/api/cases/{case_id}/trash/{deleted['trash']}/restore")
    assert restored.status_code == 200, restored.text
    assert case.timeline_page(categories=["statement"])["items"][0]["raw"] == "2026-09?"


def test_a_heavily_cited_claim_still_answers_with_its_own_row(client):
    """The entity scope returns every statement resting on this one, ordered by
    date — so the Claim being written can sit past the first page of its own
    response, which used to fail a write that had already been committed."""
    case_id = _case(client)
    created = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "The convoy passed the bridge", "when": "2030-01-01"},
    )
    claim_id = created.json()["entity"]["id"]
    case = Case.open(case_id)
    for index in range(201):
        case.save_temporal_claim(
            entity_id=None,
            label=f"Supporting reading {index:03d}",
            attrs={"when": "2020-01-01"},
            connectors={"cites": [claim_id]},
            by="user",
        )

    updated = client.patch(
        f"/api/cases/{case_id}/timeline/claims/{claim_id}", json={"when": "2030-02-02"}
    )

    assert updated.status_code == 200, updated.text
    assert updated.json()["temporal"]["owner_id"] == claim_id
    assert updated.json()["temporal"]["raw"] == "2030-02-02"


def test_media_metadata_and_case_activity_are_separate_categories(client):
    case_id = _case(client)
    case = Case.open(case_id)
    media = case.add_entity(
        "media", "Clip", {"path": "media/clip.mp4", "kind": "video"}, by="user"
    )
    case.upsert_media_item(
        {
            "path": "media/clip.mp4",
            "filename": "clip.mp4",
            "kind": "video",
            "taken_at": "2024-02-03T10:11:12Z",
            "added_at": "2026-08-11T10:00:00Z",
            "source": {"type": "download", "upload_date": "20240204"},
        },
        entity_id=media["id"],
    )

    default = client.get(f"/api/cases/{case_id}/timeline").json()
    activity = client.get(
        f"/api/cases/{case_id}/timeline", params={"category": "case_activity"}
    ).json()

    assert {item["kind"] for item in default["items"]} == {"captured", "published"}
    assert [item["kind"] for item in activity["items"]] == ["added"]


def test_a_file_row_carries_the_preview_the_case_already_cached(client):
    """A card on a zoomed axis shows the picture: the row brings the cached thumbnail,
    and a row whose owner has none, or is not a file, brings nothing."""
    case_id = _case(client)
    case = Case.open(case_id)
    shown = case.add_entity("media", "Frame", {"path": "media/frame.jpg", "kind": "image"}, by="user")
    bare = case.add_entity("media", "Clip", {"path": "media/clip.mp4", "kind": "video"}, by="user")
    for entity, path, thumb in ((shown, "media/frame.jpg", ".thumbs/frame.jpg"), (bare, "media/clip.mp4", None)):
        case.upsert_media_item(
            {
                "path": path, "filename": path.rsplit("/", 1)[1], "kind": "image",
                "taken_at": "2024-02-03T10:11:12Z", "added_at": "2026-08-11T10:00:00Z",
                **({"thumbnail": thumb} if thumb else {}),
            },
            entity_id=entity["id"],
        )
    _entity(client, case_id, "claim", "Seen the same day", {"when": "2024-02-03"})

    items = client.get(
        f"/api/cases/{case_id}/timeline", params={"category": ["media", "statement"]}
    ).json()["items"]
    thumbs = {item["owner_id"]: item.get("thumb") for item in items}

    assert thumbs[shown["id"]] == ".thumbs/frame.jpg"
    assert thumbs[bare["id"]] is None
    assert all("thumb" not in item for item in items if item["category"] == "statement")


def test_a_track_can_hold_back_the_files_the_case_made_itself(client):
    """The Media Library's working-files switch, on a track: a frame and a capture stay
    off it, a download stays on, and the file a reading is focused on always shows."""
    case_id = _case(client, "Working files")
    case = Case.open(case_id)
    owners = {}
    for name, source in (("clip", "download"), ("frame", "inspect"), ("capture", "satellite")):
        entity = case.add_entity("media", name, {"path": f"media/{name}.jpg", "kind": "image"}, by="user")
        case.upsert_media_item(
            {
                "path": f"media/{name}.jpg", "filename": f"{name}.jpg", "kind": "image",
                "taken_at": "2024-02-03T10:11:12Z", "added_at": "2026-08-11T10:00:00Z",
                "source": {"type": source},
            },
            entity_id=entity["id"],
        )
        owners[entity["id"]] = name

    def read(track, **params):
        page = client.get(f"/api/cases/{case_id}/timeline", params={
            "category": "media", "track": json.dumps(track), **params,
        })
        assert page.status_code == 200, page.text
        return {owners[item["owner_id"]]: item["produced_here"] for item in page.json()["items"]}

    assert read({}) == {"clip": False, "frame": True, "capture": True}
    assert read({"collected_only": True}) == {"clip": False}
    for spread in ("false", "true"):
        assert read({"collected_only": True}, spread=spread, limit=1) == {"clip": False}
    frame = next(owner for owner, name in owners.items() if name == "frame")
    assert read({"collected_only": True}, entity=frame) == {"frame": True}


def test_schema_15_backfills_existing_claims_and_media(tmp_path):
    db = tmp_path / "case.db"
    from azimut.sqlite_backend import SqliteCase

    store = SqliteCase.create(db, name="Migration")
    claim = store.add_entity(
        "claim", "Existing event", {"when": "2026-08-11"}, by="user"
    )
    media = store.add_entity(
        "media", "Existing photo", {"path": "media/photo.jpg", "kind": "image"}, by="user"
    )
    store.upsert_media_item(
        {
            "path": "media/photo.jpg",
            "filename": "photo.jpg",
            "kind": "image",
            "taken_at": "2024-02-03T10:11:12Z",
            "added_at": "2026-08-11T10:00:00Z",
            "source": {"type": "upload"},
        },
        entity_id=media["id"],
    )
    with closing(sqlite3.connect(db)) as conn, conn:
        conn.execute("DROP TABLE temporal_items")
        conn.execute("UPDATE meta SET value = '14' WHERE key = 'schema_version'")
        conn.execute("DELETE FROM schema_migrations WHERE version >= 15")

    reopened = SqliteCase.open(db)

    assert SQLITE_SCHEMA >= 15, "the projection this test rewinds past is gone"
    items = reopened.timeline_page(categories=["statement", "media"])["items"]
    assert {(item["owner_id"], item["kind"]) for item in items} == {
        (claim["id"], "claim"),
        (media["id"], "captured"),
    }


def test_timeline_track_filters_through_named_claim_connectors(client):
    case_id = _case(client, "Track query")
    person = _entity(client, case_id, "person", "Witness")
    place = _entity(client, case_id, "place", "North gate", {"lat": 1, "lon": 2})
    source = _entity(
        client, case_id, "bookmark", "Archived report", {"url": "https://example.test"}
    )
    first = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={
            "statement": "Witness reached the gate",
            "when": "2026-08-12T10:00:00Z",
            "about": [person["id"]],
            "at": [place["id"]],
            "cites": [source["id"]],
        },
    ).json()["temporal"]
    client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Unrelated event", "when": "2026-08-12T11:00:00Z"},
    )

    people = client.get(
        f"/api/cases/{case_id}/timeline",
        params={
            "category": "statement",
            "track": json.dumps({"relation": "about", "terms": {"type": "person"}}),
        },
    )
    assert people.status_code == 200, people.text
    assert [item["id"] for item in people.json()["items"]] == [first["id"]]
    assert people.json()["items"][0]["subject_entities"] == [
        {"id": person["id"], "label": "Witness", "type": "person"}
    ]

    sourced = client.get(
        f"/api/cases/{case_id}/timeline",
        params={"category": "statement", "track": json.dumps({"relation": "source"})},
    )
    assert [item["id"] for item in sourced.json()["items"]] == [first["id"]]

    # The Board's question about what a claim lacks reaches a track the same way.
    unsourced = client.get(
        f"/api/cases/{case_id}/timeline",
        params={
            "category": "statement",
            "track": json.dumps({"relation": "owner", "terms": {"lacks": "source"}}),
        },
    )
    assert unsourced.status_code == 200, unsourced.text
    assert [item["label"] for item in unsourced.json()["items"]] == ["Unrelated event"]


def test_timeline_track_can_filter_role_and_hide_one_entry(client):
    case_id = _case(client, "Track role")
    observed = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={
            "statement": "Observed event",
            "when": "2026-08-12T10:00:00Z",
            "time_role": "observed",
        },
    ).json()["temporal"]
    client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={
            "statement": "Occurred event",
            "when": "2026-08-12T11:00:00Z",
            "time_role": "occurred",
        },
    )
    response = client.get(
        f"/api/cases/{case_id}/timeline",
        params={
            "category": "statement",
            "track": json.dumps({"roles": ["observed"], "hidden": [observed["id"]]}),
        },
    )
    assert response.status_code == 200, response.text
    assert response.json()["items"] == []


def test_timeline_rejects_an_oversized_track_query(client):
    case_id = _case(client, "Large track query")
    with pytest.raises(HTTPException) as raised:
        timeline(
            case_id,
            from_=None,
            to=None,
            category=None,
            entity=None,
            include_undated=True,
            limit=100,
            cursor=None,
            bucket=None,
            track=json.dumps({"terms": {"q": "x" * (64 * 1024)}}),
        )

    assert raised.value.status_code == 400
    assert raised.value.detail == "timeline track query is too large"


def test_board_graph_and_map_share_the_same_fact_time_window(client):
    case_id = _case(client, "Timeline handoffs")
    person = _entity(client, case_id, "person", "Witness")
    place = _entity(
        client,
        case_id,
        "place",
        "North gate",
        {"lat": 48.8566, "lon": 2.3522},
    )
    source = _entity(
        client,
        case_id,
        "bookmark",
        "Camera log",
        {"url": "https://example.test/log"},
    )
    inside = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={
            "statement": "Witness reached the gate",
            "when": "2026-08-12T10:00:00Z",
            "about": [person["id"]],
            "at": [place["id"]],
            "cites": [source["id"]],
        },
    ).json()
    outside = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Later event", "when": "2026-08-13T10:00:00Z"},
    ).json()
    params = {
        "temporal_from": "2026-08-12T09:00:00Z",
        "temporal_to": "2026-08-12T11:00:00Z",
        "temporal_category": "statement",
    }

    board = client.get(f"/api/cases/{case_id}/catalog/entities", params=params)
    assert board.status_code == 200, board.text
    board_ids = {entity["id"] for entity in board.json()["items"]}
    assert board_ids == {
        inside["entity"]["id"], person["id"], place["id"], source["id"]
    }
    assert outside["entity"]["id"] not in board_ids

    graph = client.get(f"/api/cases/{case_id}/graph", params=params)
    assert graph.status_code == 200, graph.text
    assert {node["id"] for node in graph.json()["nodes"]} == board_ids

    mapped = client.get(
        f"/api/cases/{case_id}/timeline/map",
        params={"from": "2026-08-12T09:00:00Z", "to": "2026-08-12T11:00:00Z"},
    )
    assert mapped.status_code == 200, mapped.text
    body = mapped.json()
    assert body["matched"] == 1
    assert body["mapped"] == 1
    assert body["marks"] == 1
    assert body["items"][0]["owner_id"] == inside["entity"]["id"]
    assert body["items"][0]["place_entities"] == [{
        "id": place["id"],
        "label": "North gate",
        "lat": 48.8566,
        "lon": 2.3522,
        "radius_m": None,
        "footprint": None,
    }]


def test_map_layer_answers_every_way_the_case_puts_something_on_the_ground(client):
    """A window of photographs is a window with places in it.

    `at` is a Claim's connector and nothing else carries it, so a layer that asked
    for it alone answered a case full of located photographs with an empty map and
    the words "nothing carries a place".
    """
    case_id = _case(client, "Placed by every verb")
    case = Case.open(case_id)
    quay = _entity(client, case_id, "place", "Quay", {"lat": 43.29, "lon": 5.37})
    yard = _entity(client, case_id, "place", "Yard", {"lat": 43.31, "lon": 5.39})

    photo = case.add_entity(
        "media", "Quayside", {"path": "media/quay.jpg", "kind": "image"}, by="user"
    )
    case.upsert_media_item(
        {
            "path": "media/quay.jpg",
            "filename": "quay.jpg",
            "kind": "image",
            "taken_at": "2026-08-12T10:30:00Z",
            "added_at": "2026-08-12T10:30:00Z",
            "source": {"type": "upload"},
        },
        entity_id=photo["id"],
    )
    case.add_link(photo["id"], quay["id"], "located-at", by="user")

    shed = _entity(client, case_id, "structure", "Shed")
    case.add_link(shed["id"], yard["id"], "sited-at", by="user")
    # A note merely referring to a place was never there, so `mentions` stays out.
    note = case.add_entity("note", "Desk note", {}, by="user")
    case.add_link(note["id"], quay["id"], "mentions", by="user")

    window = {"from": "2026-08-12T00:00:00Z", "to": "2026-08-13T00:00:00Z"}
    body = client.get(f"/api/cases/{case_id}/timeline/map", params=window).json()

    placed = {item["owner_id"]: item for item in body["items"]}
    assert photo["id"] in placed, "a located photograph belongs on the map"
    assert [place["id"] for place in placed[photo["id"]]["place_entities"]] == [quay["id"]]
    assert note["id"] not in placed

    # Whatever the case has sited somewhere lands there too, in the category that
    # holds it: the structure is on the ground even though nothing was claimed of it.
    # Filing stamps the row with the wall clock, so this window is the case's life.
    filed = client.get(
        f"/api/cases/{case_id}/timeline/map",
        params={"from": "2000-01-01", "to": "2999-01-01", "category": "case_activity"},
    ).json()
    sited = {item["owner_id"]: item for item in filed["items"]}
    assert [place["id"] for place in sited[shed["id"]]["place_entities"]] == [yard["id"]]

    # The owner travels with the mark, so the card can hand the row back to the tool
    # that owns it and show a photograph as a photograph.
    owner = placed[photo["id"]]["owner"]
    assert owner["type"] == "media"
    assert owner["attrs"]["path"] == "media/quay.jpg"

    # Categories are the caller's, not this route's: asking for statements alone
    # leaves the photograph out.
    claims_only = client.get(
        f"/api/cases/{case_id}/timeline/map", params={**window, "category": "statement"}
    ).json()
    assert photo["id"] not in {item["owner_id"] for item in claims_only["items"]}

    bad = client.get(
        f"/api/cases/{case_id}/timeline/map", params={**window, "category": "nonsense"}
    )
    assert bad.status_code == 400


def test_fact_time_filter_is_not_the_filing_date_filter(client):
    case_id = _case(client, "Separate time meanings")
    claim = client.post(
        f"/api/cases/{case_id}/timeline/claims",
        json={"statement": "Historical event", "when": "1999-01-01"},
    ).json()["entity"]

    response = client.get(
        f"/api/cases/{case_id}/catalog/entities",
        params={
            "temporal_from": "1999-01-01",
            "temporal_to": "1999-01-01",
            "temporal_category": "statement",
        },
    )
    assert response.status_code == 200, response.text
    assert [entity["id"] for entity in response.json()["items"]] == [claim["id"]]

    filed = client.get(
        f"/api/cases/{case_id}/catalog/entities",
        params={"since": "1999-01-01", "until": "1999-01-01"},
    )
    assert filed.status_code == 200, filed.text
    assert filed.json()["items"] == []