> For the complete AWA documentation index, see [`llms.txt`](../llms.txt).

# Admin dashboard observation

The dashboard observes ordinary owning APIs through polling. One scheduler per
visible tab combines initial reads, periodic polling, independent reconciliation,
mutation invalidations, focus/resume and explicit refresh. There is no streaming
endpoint, database notification listener or worker execution-path change.

Managed views cover jobs and detail, filtered counts, DLQ and depth, queues and
queue runtime, workers/runtime, cron/reconciliation, batch operations, storage and
statistics. Catalog/kinds and search suggestions retain their existing policies.
Backend origin, trusted-admin scope, full query/filter and page identify a key.
Duplicate observers share admission; excess keys fail visibly without eviction.

The experimental client policy permits 16 active exact keys and two concurrent
managed reads. Cached reads respect the advertised interval (at least five
seconds); uncached reads have a two-second floor. Local dirty demand becomes
eligible after 100 ms from the first mark, subject to cooldown and backoff.
Reconciliation is independently armed before the initial automatic read, with
bounded jitter from 27 to 30 seconds; only a successful read renews the successful
observation. These are scheduling bounds, not a promise of maximum data age.
Repeated failures back off to 60 seconds. HTTP 429/503 Retry-After applies across
managed reads, and 401/403 stops retries until explicit user action. HTML responses,
redirects and malformed JSON fail instead of appearing as empty results.

The 35-second compatibility client deadline includes response-body decoding. It runs separately
from the read, aborts cancellation-aware work and fences late results before
React Query can publish them. Expiry is checked again even if the event loop
delayed the timer. Dirty demand remains pending. Client configuration must stay
finite and above the dependency's current 30-second listing/count budget. The
ADR's 20-second client target requires the separate 15-second server layer;
this increment does not advertise that target as implemented.
These interactive observation deadlines/admission limits do not apply to ADR-049
batch-operation execution scans or DLQ bulk retry/purge/move
mutations. Those retain their own operation policies. Polling their list/status
reads remains managed; cancelling a status read does not cancel the operation.
The explicit `apiRead` helper inherits observation cancellation regardless of
HTTP method, including future POST query adapters. Mutation helpers use the
separate transport without that ambient signal. Batch preview is an interactive
read, not an execution scan; its operator-triggered form still needs migration
into shared admission/deadline handling, so this increment makes no complete
preview-budget claim.

Hidden tabs and pagehide cancel reads and timers. BFCache restoration performs
one paced resynchronization. An empty managed scope has no resource timer or
resource reads. A mark during an in-flight read survives its response. Filter/view
changes retire old requests; jobs/DLQ lists may retain visibly marked previous
results while the replacement read completes. Job selection and operator form
state are retained. Selected job lists pause automatic replacement; explicit
refresh uses the same scheduler. Counts become stale on automatic marks, and
fetch only on filter change or explicit refresh.

## Aggregate cache behavior

The stats, queue list, runtime, queue-runtime and storage caches use monotonic
local generations. After a successful local admin mutation, the shared helper
advances generations and invalidates old entries. DLQ retry/purge/move and batch
cancellation use the same helper. Errors/rolled-back operations do not invalidate.
A request after invalidation cannot join an older fill; an obsolete result cannot
be returned as current. At most two generation attempts are made. Four expensive
aggregate fills share a process budget with at most 16 waiters and a single
250 ms admission window, including generation retries. Cache hits bypass fill
admission. Admission excess returns 429 and generation churn returns 503, both
with Retry-After. This aggregate budget is narrower than a whole-server read
budget.

Aggregate responses preserve existing JSON payloads and add:

| Header | Meaning |
| --- | --- |
| `X-Awa-Observed-At` | UTC source-fetch start, conservatively preceding composite queries. |
| `X-Awa-Served-At` | Response creation time. |
| `X-Awa-Cache-Age-Ms` | Monotonic elapsed age since that source-fetch start. |

Cache hits preserve the source time. A response served now is not a new source
sample. Each process owns its caches; worker/peer changes converge through TTL
and scheduled reads. Worker liveness remains heartbeat evidence. Replica lag is
unknown unless separately measured. Storage history remains client accumulation,
not server-retained history. Read-only mode still exposes sensitive admin data;
existing ingress/private-network controls remain necessary.

## Increment boundary and validation

This increment implements scheduler/lifecycle and aggregate-cache portions of the
polling-first ADR-050 contract reviewed at `4649c56932955416d2fee55accec277b32be5c78`.
It is based on filtering PR #572 at
`15b8e3ff66282cac00b744b6d0483ce2eb4f8cea`. It retains that compiler, current
safe-integer ID rejection, GET payloads and `/api/dlq/retry-matching` and
`/api/dlq/purge-matching` mutation protocols.

Strict versioned JSON read adapters/capabilities, origin-policy isolation and API
fallback hardening are separate work. This slice still uses the existing GET
reads and does not establish a strict mixed-server filtered-read guarantee.
The dependency now rejects unknown/empty GET parameters and supplies one
30-second listing/count budget across candidate passes and row loads, with
server statement timeouts and a pool-wait backstop. Batch execution scans retain
their own policy. This is narrower than the ADR's proposed process-wide read
admission, 15-second whole-read deadline including serialization, five-second SQL
and one-second lock limits. The aggregate admission window and client abort do
not prove SQL rollback/cancellation or safe pool reuse; those need independently
tested shared read-layer coverage. Operator-triggered preview admission and
consistent observation metadata beyond the five aggregate endpoints are also
not completed here.
These limitations must be resolved before claiming complete observation-v1
acceptance; client timeouts must never reset a server deadline.

Run `npm run test:observation` in `awa-ui/frontend` for dependency-free scheduler,
HTTP, cancellation and lifecycle tests. Rust cache tests use deterministic barriers
for an old fill finishing after invalidation, bounded churn, waiter cancellation
and monotonic cache age. The full React/build and PostgreSQL 17/18 suites remain
necessary, including real cancellation/pool recovery, rollback/peer convergence,
selection/draft behavior and page refill. Load/ingress/pooler measurements remain
outstanding; no production freshness SLO follows from these defaults.
