# v0.106.0: Executed package qualification and database cost

> **Status:** Planned
> **Scope:** Large
> **User promise:** "Package support and performance claims identify the tests and measurements behind them."
> **Blocked by:** [v0.105.3](v0.105.3.md)
> **Source:** [Post-v0.105.2 assessment](../pg-trickle-v0.105.2-assessment.md), sections 4.2 through 4.5

## Outcome

Close the gap between the existing qualification contract and the evidence
required to publish a release. Qualify the chosen PostgreSQL 18 support
boundary with real package installs, pending-data upgrades, and database
workloads. Broader platform claims require their own executed evidence.

## Work

### Bind evidence to execution

- Extend `scripts/release_evidence.py` and the qualification JSON contract.
  Test jobs emit structured results with candidate commit, artifact digest,
  platform, actual PostgreSQL version, suite identifier and version, command,
  effective workload, executed and skipped test counts, outcome, and log digest.
- Validate the required artifact-by-suite matrix for each declared support
  tier. Reject missing or duplicate records, mismatched candidates, zero-test
  required suites, empty required logs, and missing required artifacts.
- Record each budget's metric, measured value, unit, baseline or denominator,
  threshold, and verdict. Validate measurements against the contract before
  any release promotion. Preserve failed, skipped, unavailable, stale, and
  historical results instead of treating them as successful execution.

### Execute package and lifecycle checks

- Declare runtime-qualified, build-only, and best-effort platform tiers.
  Linux amd64 is the initial deep-qualification target. Every platform
  advertised as runtime-qualified must execute its promised install, active
  refresh, and lifecycle checks against its own package.
- Publish built, installed, runtime-tested, upgrade-tested, and reproducibility-
  checked status separately for each artifact. Require two clean builds and
  a documented comparison before claiming reproducibility. A checksum alone
  proves neither reproducibility nor runtime behavior.
- Run each supported prior-package upgrade with active stream tables and
  pending source changes. Install the previous published binary, accumulate
  changes, quiesce through the documented procedure, install the candidate,
  apply SQL updates and required restart steps, then resume.
- Verify result and schema parity, retained pending changes, graph bindings,
  publication state, and consumer cursors after upgrade. Exercise a supported
  recreation path separately. Retain SQL-completeness checks as static evidence.
- Run logical restore and clone isolation as separate cases. Verify local
  rebinding and rejection of stale database-instance evidence without copying
  private catalog rows or assuming stable relation OIDs.

### Measure the foreground database workload

Use three fixed workload families in the existing live benchmark suites:

| Workload | Required cases |
|----------|----------------|
| Keyed scan or small aggregate | Small deltas and mixed source writes |
| Join plus aggregate | Skew, updates, deletes, wide rows, and amplification |
| Small dependency graph | Graph V1 refresh with output consumers disabled and active |

For each workload, compare source DML without maintenance, capture with refresh
paused, and capture with active refresh. Keep data, hardware, concurrency,
durability settings, and measurement duration identical. Bound the capture-only
run and reset its backlog between trials so growth does not distort comparison.

The planned foreground budget is at most 15% p95 source-write latency overhead
against the no-maintenance baseline, reported separately for capture-only and
active-refresh runs. Calculate overhead as `100 * (measured / baseline - 1)`.
Freeze offered load, warmup, repetitions, and the measurement window in the
contract before qualification. Report throughput and errors alongside latency
so rejected or unfinished writes cannot improve the result.

Retain the existing 10% Criterion regression budget as a separate microbenchmark
check. Also record refresh p50, p95, and p99 latency, end-to-end staleness, CPU,
memory, WAL, backlog, temporary spills, output-log size, and storage growth.
Set workload-specific limits for freshness and resource use before evaluating
the candidate. Retain raw results and configuration with the package evidence.
If a workload misses a budget, fix the cause or explicitly narrow the qualified
workload boundary with a reason. Do not relabel the failed run as passed.

## Exit criteria

- [ ] Negative controls reject missing artifacts, zero-test suites, empty logs,
      candidate mismatches, and out-of-budget measurements before publication.
- [ ] Every artifact's published support tier matches its executed checks.
      Missing evidence cannot inherit another platform's qualification.
- [ ] Supported previous-binary upgrade and recreation paths preserve pending
      committed changes and pass post-upgrade parity and contract checks.
- [ ] Restore and clone cases prove database-local identity and safe rebinding.
- [ ] All three database workloads publish raw measurements, fixed baselines,
      budget verdicts, exact-result checks, and effective-strategy results.
- [ ] Public release claims distinguish static checks, microbenchmarks, live
      database tests, and unexecuted qualification.

## Existing implementation points

Extend the [evidence writer](../scripts/release_evidence.py),
[qualification contract](../tests/release/v0.105.2-qualification.json),
[release workflow](../.github/workflows/release.yml),
[upgrade suite](../tests/e2e_upgrade_tests.rs),
[live benchmarks](../tests/e2e_bench_tests.rs), and
[graph benchmarks](../tests/e2e_dag_bench_tests.rs).

## Scope control

Do not introduce another evidence framework or expand PostgreSQL major-version
support. Preserve durability, conservative capture defaults, Graph V1, and
Delta V1. This release measures existing behavior. Support documentation and
operator validation continue in [v0.107.0](v0.107.0.md). The 72-hour soak,
longevity environment, and v1.0 qualification remain deferred.