From 5d00995a1d51747b9fce03fe2a11d381c9b91d6c Mon Sep 17 00:00:00 2001 From: "agent:opencode-agent" Date: Mon, 2 Nov 2026 18:09:44 +0100 Subject: [PATCH] ticket-275: keep the stale index window longer than a real rebuild A rebuild of the production store (22 358 tickets, 517 MB) takes 5-9 minutes, but the stale-serving window was 300 s. It therefore expired inside the repair and machine callers got 503 while a coherent last-known-good snapshot existed. The window now covers a real repair and stays bounded (a permanently broken index still fails closed). While fixing it: the bounded stale helper never received require_fresh, so a caller asking for freshness was served stale data with 200 and X-Planfile-Index-State: stale. It now falls through to 503. --- planfile/api/server.py | 14 +++++++++- project/TICKETS.md | 1 + project/ticket-275/README.md | 42 +++++++++++++++++++++++++++++ project/ticket-275/intent.json | 25 ++++++++++++++++++ tests/test_sqlite_ticket_index.py | 44 +++++++++++++++++++++++++++++++ 5 files changed, 125 insertions(+), 1 deletion(-) create mode 100644 project/ticket-275/README.md create mode 100644 project/ticket-275/intent.json diff --git a/planfile/api/server.py b/planfile/api/server.py index 8f3c65df..156b5339 100644 --- a/planfile/api/server.py +++ b/planfile/api/server.py @@ -467,7 +467,13 @@ def _validate_completion_receipt(receipt: dict[str, Any] | None, ticket_id: str) _TICKET_LIST_RESPONSE_MIN_MAX_BYTES = 1024 * 1024 _TICKET_LIST_RESPONSE_MAX_MAX_BYTES = 512 * 1024 * 1024 _DASHBOARD_STALE_WINDOW_SECONDS = 30.0 -_INDEX_REPAIR_STALE_WINDOW_SECONDS = 300.0 +# A repair on the production store (about 22k tickets, 517 MB) takes 5-9 minutes, so a +# five-minute window expires in the middle of it: the projection is still a coherent +# last-known-good snapshot, yet machine callers were answered with 503 and clients saw an +# API that flapped on every write. The window stays bounded - a permanently broken index +# must still fail closed, and `require_fresh` never accepts stale data - but it now covers +# a real repair rather than a guess at one. +_INDEX_REPAIR_STALE_WINDOW_SECONDS = 3600.0 _SPRINT_SUMMARY_CACHE: dict[str, tuple[tuple[int, int], dict[str, Any]]] = {} _SPRINT_SUMMARY_CACHE_LOCK = RLock() @@ -666,8 +672,13 @@ def _bounded_stale_index_response( limit: int | None, view: Literal["full", "operational", "summary"], allow_unbounded_summary: bool = False, + require_fresh: bool = False, ) -> Response | None: """Serve a recent, coherent projection while its source index is repaired.""" + if require_fresh: + # The caller asked for freshness, not for availability: a marked-stale body is + # still stale data, so it must fall through to the explicit 503 instead. + return None archive_queue = sprint == "all" and limit is not None legacy_summary = allow_unbounded_summary and view == "summary" if view == "full" or not (archive_queue or legacy_summary): @@ -862,6 +873,7 @@ def _ticket_list_response( limit=limit, view=view, allow_unbounded_summary=allow_stale or allow_index_stale, + require_fresh=require_fresh, ) if stale_index_response is not None: return stale_index_response diff --git a/project/TICKETS.md b/project/TICKETS.md index 560a5551..4306e4a8 100644 --- a/project/TICKETS.md +++ b/project/TICKETS.md @@ -172,4 +172,5 @@ This file indexes governance tickets without taking ownership of | **ticket-271** | [`README.md`](./ticket-271/README.md) | - | - | - | - | - | | **ticket-272** | [`README.md`](./ticket-272/README.md) | - | - | - | - | - | | **ticket-273** | [`README.md`](./ticket-273/README.md) | - | - | - | - | - | +| **ticket-274** | [`README.md`](./ticket-274/README.md) | - | - | - | - | - | diff --git a/project/ticket-275/README.md b/project/ticket-275/README.md new file mode 100644 index 00000000..028557f9 --- /dev/null +++ b/project/ticket-275/README.md @@ -0,0 +1,42 @@ +# Ticket 275: Keep the stale index window longer than a real rebuild + +- **ID**: ticket-275 +- **Owner**: agent:opencode-agent +- **Status**: IN_PROGRESS +- **Workflow state**: PUBLICATION + +## Goal + +The Planfile HTTP API flapped between 200 and 503 while an index rebuild was running, even +though a coherent last-known-good snapshot existed the whole time. + +Two defects sit behind that: + +1. `_INDEX_REPAIR_STALE_WINDOW_SECONDS` was `300.0`, but a rebuild of the production store + (about 22 358 tickets, 517 MB) takes **5-9 minutes** (measured twice on 2026-11-02: + ~5 min and ~9 min). The window therefore expired *inside* the repair, and machine callers + were answered `503`. +2. `_bounded_stale_index_response()` never received `require_fresh`, so a caller that asked + for freshness was served a **stale** body with `200` and `X-Planfile-Index-State: stale`. + The freshness guarantee only covered the in-memory cache path. + +## Change + +- The stale window now covers a real repair (1 hour). It stays bounded: a permanently + broken index still fails closed, and `require_fresh` never accepts stale data. +- `require_fresh=True` returns `None` from the stale helper so the request falls through to + the explicit `503` instead of receiving stale content. + +## Acceptance criteria + +- [x] AC-01: a 20-minute-old coherent snapshot is served with `X-Planfile-Index-State: stale` + instead of `503` (previously impossible: 300 s window). +- [x] AC-02: `require_fresh=true` never returns stale data - it answers `503`. +- [x] AC-03: the in-memory stale path keeps its existing `require_fresh` guard. + +## Evidence + +- `pytest tests/test_sqlite_ticket_index.py` -> 76 passed (includes the new + `test_stale_index_survives_a_repair_longer_than_five_minutes_but_never_lies`). +- Live measurement before/after: `12/12` probes at 0.07-0.53 s once `current`, then `503` + at 5-19 s during the next repair; the window is the difference between those two states. diff --git a/project/ticket-275/intent.json b/project/ticket-275/intent.json new file mode 100644 index 00000000..5b254f35 --- /dev/null +++ b/project/ticket-275/intent.json @@ -0,0 +1,25 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-275", + "summary": "Keep the stale index window longer than a real rebuild so the API stops flapping with 503", + "workstream": "application", + "classification": { + "kind": "BUG", + "priority": "P1", + "origin": "health" + }, + "allowedPaths": [ + "project/ticket-275/**", + "TODO.md", + "project/TICKETS.md", + "planfile/api/server.py", + "tests/test_sqlite_ticket_index.py" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md" + ], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null +} diff --git a/tests/test_sqlite_ticket_index.py b/tests/test_sqlite_ticket_index.py index b3f0fc14..64219d79 100644 --- a/tests/test_sqlite_ticket_index.py +++ b/tests/test_sqlite_ticket_index.py @@ -841,6 +841,50 @@ def test_stale_archive_queue_reads_use_recent_index_without_query_cache( assert pf.store.ticket_index_status()["current"] is False +def test_stale_index_survives_a_repair_longer_than_five_minutes_but_never_lies( + tmp_path, monkeypatch +): + """A repair takes 5-9 minutes, so a 300 s window handed machine callers a 503 mid-repair.""" + pf = Planfile(str(tmp_path)) + _disable_archive(pf) + ticket = pf.create_ticket(name="Last known good after a long repair") + pf.store.configure_ticket_index(True) + + sprint_file = pf.store._sprint_file("current") + data = yaml.safe_load(sprint_file.read_text(encoding="utf-8")) + data["sprint"]["tickets"][ticket.id]["name"] = "New durable value" + sprint_file.write_text(yaml.safe_dump(data, sort_keys=False), encoding="utf-8") + mirror_path(sprint_file).unlink(missing_ok=True) + + index = pf.store._sqlite_ticket_index() + aged_ns = time.time_ns() - 20 * 60 * 1_000_000_000 + with sqlite3.connect(index.path) as connection: + connection.execute( + "UPDATE meta SET value = ? WHERE key = 'source_indexed_at_ns'", + (str(aged_ns),), + ) + + monkeypatch.setattr(server, "get_planfile", lambda: pf) + monkeypatch.setattr( + pf.store, + "_ticket_index_records", + lambda: (_ for _ in ()).throw(AssertionError("request-triggered rebuild")), + ) + server._TICKET_LIST_RESPONSE_CACHE.clear() + server._TICKET_LIST_LATEST.clear() + client = TestClient(server.app) + + stale = client.get("/tickets?sprint=all&view=summary&limit=100") + + assert stale.status_code == 200 + assert stale.json()[0]["name"] == "Last known good after a long repair" + assert stale.headers["X-Planfile-Index-State"] == "stale" + + fresh = client.get("/tickets?sprint=all&view=summary&limit=100&require_fresh=true") + + assert fresh.status_code == 503 + + def test_legacy_archive_dashboard_uses_recent_current_index_without_cache( tmp_path, monkeypatch ):