# Data Freshness and Materialization

Freshness is a product contract, not just a cache setting. State the source,
metric window, expected latency, TTL, and what the UI shows before deciding on a
pattern. Validate the final metric against bounded read-only SQL before calling
it ready.

## Four supported delivery shapes

| Shape | Request path | Freshness behavior | Best for |
| --- | --- | --- | --- |
| TTL-cached live SQL | Declared route runs bounded SQL on a cache miss. | TTL normally 60 to 300 seconds; use `0` only for a proven sub-minute need. | Interactive reports and joins. |
| Scheduled live-cache warming | `refresh_live_cache` fills Redis before viewer reads; live SQL remains the miss path. | Best effort; UI uses `generatedAt`, while operators monitor warm tasks. | Explicitly requested predictable live reads. |
| Precomputed dataset | Worker runs bounded SQL and writes private tenant-scoped JSON; route reads it. | No live fallback; unavailable before first warm, then last-known-good data. | Dense computation and large reports. |
| Upstream materialized table/view | Approved source/analytics data product is queried as a bounded live dataset. | Its upstream refresh cadence defines source freshness; app TTL adds its own delivery window. | Shared, durable transformations. |

`mode: "precomputed"` requires an enabled `refresh_live_cache` schedule and
`warmParams` for every declared variant. The same schedule mode may warm a live
dataset only when recurring refresh was explicitly requested. Do not use
`precompute_static` for cache-only work. Pass `refreshNow: true` after a new or
changed precomputed dataset so the first private object exists before smoke.

`precompute_static` is for rebuilding precomputed HTML/assets; its schedule is
part of the manifest-owned app contract. `maintenance` is available for
maintenance work. All schedules declare a five-field cron, timezone, prompt,
and optional enabled/output-strategy settings. `commit_artifact` syncs them as
manifest-owned Platform schedules; do not create a raw scheduler job or a
separate duplicate manual schedule.

## Implementation checklist

1. Discover catalog resources, describe the chosen resource, and prototype a
   bounded read-only query with `run_psql`.
2. Declare the final dataset SQL, matching route, and limits (`maxRows`,
   `maxBytes`, `timeoutMs`), plus TTL or precompute parameters.
3. Make the UI label its update/freshness state and handle unavailable, empty,
   partial, stale, and error results.
4. For precomputed data, declare enabled `refresh_live_cache`, use
   `refreshNow: true` when applicable, and smoke only after the route has data.
5. For upstream materialization, separately verify the upstream cadence and
   data quality; the artifact app does not own that producer.