Module stats 

Stats route module.

This module provides the aggregate statistics endpoint (GET /api/v1/stats) for the daemon. The stats endpoint returns read-only operational summaries derived from authoritative state without speculation, consistent with actionqueue-charter.md, actionqueue-scope-appendix-v0.1.md, and invariant boundaries in invariant-boundaries-v0.1.md.

Overview

Stats are derived from:

• Total task count from the task projection
• Runs by state (Scheduled, Ready, Leased, Running, RetryWait, Completed, Failed, Canceled)
• Total run count
• Total attempt count derived from run instances
• Latest sequence number from the WAL projection

Scheduling lag

Scheduling lag is intentionally omitted in S1 because there is no authoritative clock injection in the daemon. Do not derive scheduling lag from system time or any non-authoritative source. If scheduling lag becomes necessary in a future release, an authoritative time source must be added to the daemon bootstrap state.

Invariant boundaries

The stats handler performs no IO, writes no WAL entries, and mutates no runtime state. It reflects the authoritative projection state from bootstrap.

Response schema

{
  "total_tasks": 5,
  "total_runs": 12,
  "attempts_total": 20,
  "runs_by_state": {
    "scheduled": 2,
    "ready": 3,
    "leased": 1,
    "running": 4,
    "retry_wait": 0,
    "completed": 1,
    "failed": 0,
    "canceled": 1
  },
  "latest_sequence": 42
}

Structs

StatsResponse

Stats response payload.

StatsRunsByState

Counts of runs by state.

Functions

handle

Stats handler.

register_routes

Registers the stats route in the router builder.