PT-803: the flow-metrics read API over the `task_flow_events` capture stream (PT-801/PT-802)

GET 
/api/projects/:id/flow-metrics

PT-803: the flow-metrics read API over the task_flow_events capture stream (PT-801/PT-802). Returns four series in ONE payload — cumulative flow, review-queue depth/age, rework rate, and cycle time by agent class — because the first three derive from ONE scan of the same window; a chart-per-endpoint split would repeat that scan for a response measured in kilobytes. (Cycle time is the series that scan cannot answer on its own — a task completed inside the window may have started long before it — so it adds a second, targeted read for completions and their histories.) The cumulative-flow and review-queue series are built by reconstructing each task’s timeline PER TASK from that task’s own transitions, walking backward from live state, and their population figures are a COUNT OF TASKS rather than an accumulated +1 to_category / −1 from_category delta: a cross-project move, which the stream records with no discriminator, can therefore misplace at most the one task it belongs to instead of desynchronising the whole series. Rework and cycle time do not use that reconstruction — rework buckets qualifying events directly, and cycle time works from the histories of the tasks that completed inside the window. The window is the RESOLVED one, not necessarily the requested one: to is capped at the present (sampling the future would report fabricated history, since the reconstruction projects each task’s live status forward) and an over-long range clamps its LEFT edge. A third normalisation is silent: the grammar accepts arbitrary fractional seconds, but the value is carried as a JS Date and so is TRUNCATED to milliseconds — …:00.123999Z becomes …:00.123Z, which is what the returned window reports and what the exclusive-from / inclusive-to predicates apply, while the stored timestamps keep microsecond precision. Sub-millisecond boundary membership is therefore unreliable (PT-913). truncated reports when an internal row cap clipped the reads. Residuals a chart reader must not misread as data are documented at /modules/project-tracker/flow. Gated on projects.read | projects.read.own evaluated against the project’s own org (plus project access), like the sibling flow-counts and overview reads.

Request

Responses

200

Successful response

400

Unparseable from/to, unknown interval, from at or after the EFFECTIVE to (which is capped at the present, so a wholly-future window is rejected), or any of the three supplied more than once — a repeated parameter is rejected rather than silently resolved to one of its values, even when each value is individually valid.

401

Unauthorized — no authenticated user.

403

Forbidden — requires projects.read | projects.read.own against the project’s own org, plus project access. This route’s own gate is deliberately UNIFORM across a malformed id, an unknown project, one the caller cannot reach, and a genuine permission denial (anti-enumeration), so it is never a 404 and its flat body does not say which applied. The { error: { code, message } } variant is produced earlier, by the shared tenant handler that wraps this route — see withTenantHandler for the conditions under which it denies.