# v0.93.0 — Defaults, Bounds & Diagnosis

> **Status:** Planned
> **Scope:** Large
> **User promise:** *"I can run this for years without hidden resource or repair behavior."*
> **Blocked by:** [v0.92.0](v0.92.0.md)
> **Renumbered:** previously v0.92.0. Monitoring, assurance, and packaging are
> in [v0.94.0](v0.94.0.md).

## Theme

Make the default configuration derive from real resource constraints. Define
which resources pg_trickle can bound, which it can throttle, and which it can
only forecast and react to. Long operations, errors, and privilege decisions
must be inspectable through stable interfaces.

This release is part of the mandatory v1.0 operational critical path.

## Items

### PP-1: Resource-based defaults

Automatic configuration uses available memory, PostgreSQL worker limits, CPU,
container or cgroup limits when discoverable, connection limits, and the
configured pg_trickle resource policy. Labels such as `laptop`, `managed`, and
`dedicated` may explain the selected settings, but labels do not drive the
decision.

`pgtrickle.active_profile()` and `explain()` report every detected constraint,
selected value, override, and missing signal. Standard benchmark deployments
must need no manual tuning.

### PP-2: Honest resource guarantees

Every resource has one documented enforcement class.

| Class | Resources | Behavior |
|-------|-----------|----------|
| Hard bound | Extension-managed memory, worker count, retained internal history, internal queue size | Reject or pause work before crossing the configured limit. |
| Throttled | CPU use, concurrent refreshes, connections | Reduce admission and concurrency while preserving committed changes. |
| Forecast and react | WAL volume and disk growth caused by continued source activity | Warn, throttle, suspend, or breach freshness deliberately before correctness is at risk. |

`pgtrickle.disk_usage()` reports current and projected use by stream table.
`health_check()` warns before forecast growth consumes the configured headroom.
The documentation does not claim an absolute bound where PostgreSQL or source
activity prevents one.

### PP-3: Progress reporting

A `pg_stat_progress_pgtrickle`-style view reports initial population, FULL
refresh, rebuild after `ALTER`, and reinitialization after repair. Each row has
a stable operation identifier, phase, rows processed, estimated rows, elapsed
time, and last progress timestamp.

### PP-4: Stable error surface

Audit every user-visible error and warning. Each operational condition has a
stable machine-readable identifier, an accurate SQLSTATE, object-specific
detail, and an actionable hint. Automation must not parse message text.

A CI check prevents undocumented identifiers and errors without a documented
remediation from entering SQL-facing code.

### PP-6: Predefined roles

Provide `pg_trickle_admin`, `pg_trickle_operator`, and `pg_trickle_reader` as a
user-facing mapping onto the ACL and ownership model from v0.84.0. The roles do
not create a second authorization layer. Positive and negative tests cover each
lifecycle and diagnostic operation, including RLS and `SECURITY DEFINER`
boundaries.

## Exit criteria

- [ ] Standard benchmark deployments require no manual tuning, and every
      automatic choice reports its resource evidence
- [ ] Every resource has a documented enforcement class and a pressure test
- [ ] Pressure tests degrade by throttling, explicit freshness breach, or
      suspension without losing committed changes
- [ ] Progress reporting covers every long-running lifecycle operation
- [ ] User-facing errors have stable identifiers, SQLSTATEs, details, and
      actionable hints
- [ ] Predefined roles match the v0.84.0 ACL matrix and pass positive and
      negative boundary tests