# R2 Resource Containment And Safe Publication Plan

This plan executes full-engine checkpoints 1B and 1C for the pgGraph 1.0
release. Each checkpoint must keep PostgreSQL tables authoritative, preserve
the last usable projection on failure, update public documentation, and retain
repeatable evidence under `todo/measurements/`.

## R2A: Typed Resource Policy And Build Rejection — Complete

- Introduce checked byte, memory-budget, and elapsed-time domain types at one
  resource-policy boundary. Add disk, row, and work units with their first
  enforced R2B/R2C consumers rather than as dormant abstractions.
- Add a statement-local governor with named phases, fallible reservations,
  peak accounting, and RAII release.
- Make build orchestration the only owner of build-memory preflight and express
  estimates in integer bytes rather than rounded MiB.
- Treat unknown source statistics conservatively and reject arithmetic
  overflow. R2B adds runtime enforcement for stale positive estimates.
- Keep legacy `graph.oom_action` spellings readable for 1.x compatibility, but
  reject over-budget construction for every setting. Read-only remains a
  serving/mutation state, not permission to perform an unsafe build.

Exit evidence: governor unit/property tests, PostgreSQL build rejection tests,
formatting, Clippy, rustdoc, documentation/contract drift, and focused review.

## R2B: Enforced Build Reservations And Adaptive Batches — Complete

- Resolve the effective build budget from the configured cap minus current
  backend-private graph residency and a documented safety reserve.
- Reserve phase workspace before growing node, relationship, filter,
  resolution, and persistence buffers; use `try_reserve` after the lease.
- Replace fixed row-only build batches with bounded byte-adaptive batches.
- Report resolved budget, current/peak bytes, peak phase, and pressure events.

Exit evidence: stale/no-statistics, long-key, wide-filter, and low-memory build
profiles fail before allocation or stay within the declared envelope.

## R2C: Load, Query, Sync, Compaction, And Analytics Breakers — Complete

- Apply the same governor to mapped-load metadata, source candidates,
  expansions, frontiers, paths, hydration, blocking operators, sync
  normalization, compaction, and analytics workspaces.
- Add byte, row, work, disk, and elapsed breakers with interrupt checks.
- Preserve the existing backend engine and current generation on every
  reservation, validation, cancellation, or disk failure.

Exit evidence: production-shaped RSS/PSS and pathological workload gates cover
all advertised operations and return stable typed resource diagnostics.

## R2D: Generation-Safe Publication — Complete

- Publish generation-specific staged artifacts under graph-scoped
  cross-backend exclusion and compare-and-swap the current generation.
- Fsync, mmap-validate, catch up, and recheck catalog/security state before the
  current-manifest switch.
- Retain the previous serving generation through reader pins and rollback
  retention; garbage collection removes only unpinned obsolete generations.

The durable manifest pointer, cross-backend compare-and-swap, reader pins, and
bounded generation garbage collection are complete. The generation-specific
The direct v6 artifact build completes the generation-specific base switch:
staged candidates are fsynced, production-loaded, source-revalidated, and
published by generation compare-and-swap before readers can discover them.

Exit evidence: competing publisher, injected write/checksum/load/catch-up
failure, crash, old-reader, rollback, and bounded-GC tests preserve exactly one
valid current generation.

## R2 Completion

Run the full PostgreSQL 14-18 release matrix, process sanitizer, documentation
and contract drift, secrets, package/fresh-install smoke, and resource/crash
profiles. Retire KI-012, KI-013, and KI-018 only when their complete acceptance
evidence is green; partial subsystem work remains explicit in the closure
ledger.
