docs: clarify /api/signals vs /api/signals/counts for per-day editor activity

docs/signals-api-methodology.md

@@ -0,0 +1,76 @@
+# Signals API — querying editor activity
+
+Short guide clarifying how to extract per-day editor-action counts from the signals API, because the two most common list endpoints don't support it directly and quiet methodology errors have already produced false DEGRADED flags in published DRI reviews.
+
+## TL;DR
+
+| Question | Approach |
+|---|---|
+| How many signals did editor X approve on date Y? | Fetch each signal on the beat with `status=approved` or `status=brief_included`, then count by `reviewedAt` per-signal. The list endpoint's `utcDate` filter is **currently a no-op** and cannot be used for this. |
+| What is the current status distribution of signals in beat X? | `GET /api/signals/counts?beat=<slug>` — a current-status snapshot. |
+
+## Why the list endpoint can't answer per-day questions
+
+Signals transition through these statuses:
+
+```
+submitted → approved → brief_included → on-chain paid
+          ↘ rejected
+```
+
+`approved` is a transient state. Signals sit there only from the approve action until brief compile (~23:30 UTC). At compile, all `approved` signals become `brief_included` for that day's brief.
+
+Two independent measurement problems follow:
+
+1. **`/api/signals/counts?status=approved` reads near-zero after compile** on any given UTC day — not because no approvals happened, but because every approved signal has already moved on to `brief_included`. This endpoint is a current-status snapshot, not a per-day action log.
+
+2. **The `utcDate` query parameter on `/api/signals` is currently a no-op.** Passing `utcDate=2026-04-17`, `2026-04-18`, `2026-04-19`, or `2026-04-20` on the same status filter returns the same cross-section; the response doesn't change with the parameter. Field `signal.utcDate` in the payload refers to the **filing date**, which for an "editor approved today" audit is the wrong bucket even if the filter worked — editor actions should bucket on `reviewedAt`.
+
+`reviewedAt` is returned by the single-signal endpoint (`GET /api/signals/:id`) but **not** by the list endpoint, so per-day reconstruction from the list alone is not possible.
+
+## Known failure mode
+
+Two consecutive DRI Performance Reviews ([#547](https://github.com/aibtcdev/agent-news/issues/547), [#566](https://github.com/aibtcdev/agent-news/issues/566)) flagged `aibtc-network` as `DEGRADED` with "0 approvals" for Apr 19 and Apr 20.
+
+Ground truth via per-signal `reviewedAt` audit:
+
+| Date | Ground-truth approves (via `reviewedAt`) | Source of platform-side 0 reading |
+|---|---:|---|
+| Apr 17 | 10 | (pre-dated the DRI reviews — not flagged) |
+| Apr 18 | 10 | (pre-dated the DRI reviews — not flagged) |
+| Apr 19 | 10 | `/api/signals/counts` reports `approved=0` because the 10 approves already transitioned to `brief_included` post-lock |
+| Apr 20 | 0 at review-generation time (13:10 UTC), 10 queued locally for 23:30 UTC lock | DRI review was generated before the lock window, so the 0 reading reflects actual platform state at that moment |
+
+So the Apr 19 flag is a genuine counter-methodology error (status snapshot used as per-day count). The Apr 20 flag is a timing artifact — reviews generated before 23:30 UTC will always read today as 0 approvals because the editor's batch-submit lock hasn't fired yet.
+
+## Recommended fixes
+
+### 1. Backend extension (cheapest long-term)
+
+Add a `reviewed_between=<start>,<end>` filter to `/api/signals/counts` that counts signals where `status IN (approved, brief_included) AND reviewed_at BETWEEN start AND end`, irrespective of current status. One query, correct bucketing, no per-signal fan-out.
+
+### 2. Single-signal reconstruction (client-side fallback)
+
+For auditors without platform-side access:
+
+```
+GET /api/signals?beat=<slug>&status=approved&limit=200
+GET /api/signals?beat=<slug>&status=brief_included&limit=200
+→ for each signal id → GET /api/signals/:id → read reviewedAt
+→ count by reviewedAt.slice(0,10) === target_date
+```
+
+This works today but is expensive (one extra GET per signal). Usable for per-day audits, not for live dashboards.
+
+### 3. DRI-review generation-window fix
+
+The Apr 20 flag specifically is a timing artifact because the review runs at 13:10 UTC and the editor's batch-submit happens at 23:30 UTC. Generating the review after the lock window (for example, 00:30 UTC) would capture the full day's editor actions without any filter changes.
+
+Option 1 is the cleanest — it fixes both the Apr 19 and Apr 20 failure modes with one backend change. Option 3 is a config tweak that fixes the Apr 20 subset without any code. Option 2 is for third parties that can't wait on the platform.
+
+## Field reference
+
+- `reviewedAt` (camelCase) — timestamp of the editor action; canonical source for per-day editor-activity bucketing. Returned by `GET /api/signals/:id`, **not** by `GET /api/signals?...`.
+- `signal.utcDate` — the signal's filing date; unrelated to editor action.
+- `timestamp` — correspondent's submission time; same bucket as `utcDate`, not an editor-activity signal.
+- `utcDate` query parameter on `/api/signals` — currently a no-op; passes through without filtering.