partition_gardener 0.3.0

data/docs/decision_flow.md

@@ -0,0 +1,154 @@
+# Partition decision flow
+
+This document describes how to decide whether a PostgreSQL table should be partitioned, which declarative method and runtime layout to use, and how that choice maps to Partition Gardener templates. It is written for operators and application authors who maintain large tables on plain PostgreSQL without a time-series extension.
+
+The flow has four stages: whether to partition at all, which partition method fits the data shape, which maintenance layout fits the load, and which tools own DDL creation versus runtime maintenance. Reliability invariants apply at every stage.
+
+## Stage zero: whether to partition
+
+Most tables never need partitions. Partitioning adds catalog complexity, migration cost, and operational surface. Start here.
+
+Defer partitioning when the table is small and growth is modest. A common practical band is below a few hundred megabytes on disk with no retention pressure and no recurring vacuum or reindex pain on the parent. In that band, indexes, query shape, and retention policy usually deliver more than partitions.
+
+Defer partitioning when queries do not consistently filter on a single dominant dimension. If reports routinely scan wide date ranges, join many tenants in one query, or ignore the column you would partition on, the planner cannot prune children and you pay partition overhead without benefit. Plan those reports as snapshot or warehouse paths, not live OLTP aggregates. A single materialized view over all history has the same scan cost on read and does not partition; see [partition_landscape.md](partition_landscape.md#materialized-views).
+
+Defer partitioning when the real problem is a missing index or an unbounded delete. Bulk delete followed by vacuum is the wrong motivation. Partitioning pays off when you can drop or detach whole children, or when per-child maintenance and pruning match how the application reads and writes.
+
+Proceed toward partitioning when several signals agree. Table size or row count is large and still growing. You must archive or drop data by period. Most important queries include the same key you would partition on. Parent-level vacuum or index maintenance is painful. You can change primary or unique keys so every uniqueness constraint includes the partition key, which PostgreSQL requires for declarative partitions. Product surfaces can default to the same key (month picker, tenant context, date range) so routine use stays prune-friendly; see [partition_landscape.md](partition_landscape.md#ui-and-product-surfaces).
+
+## Stage one: choose the partition method
+
+The partition method follows access shape, not storage convenience.
+
+Use range partitioning when time or calendar bounds dominate. Examples are created_at, occurred_on, order_date, and business dates cast to date. Reads and writes usually carry a bounded interval on that column. Retention is expressed as dropping or detaching months or years. This is the default case for operational and audit data in Rails applications.
+
+Use list partitioning when the table splits into a small, stable set of categories that queries always filter on. Examples are region codes, product lines, or a fixed branch discriminator such as cached versus workspace-scoped rows. List is a poor fit when category membership changes often or when queries cross categories without filters.
+
+Use hash partitioning when volume is high but no natural range or list dimension exists, and equality on a single key is the main access path. Hash spreads writes; it does not help time-range reports. Changing hash modulus is a major migration and should be rare.
+
+Use composite partitioning when one dimension is stable and another needs fan-out inside each branch. A typical pattern is list at the parent for branch type, then range or hash on a high-cardinality key under each branch. This matches mixed workloads where one slice is global and cold and another is tenant-heavy and hot.
+
+Before any method is chosen, resolve uniqueness. If the business unique key does not already include the partition key, redesign the primary key or unique indexes to composite form such as id plus partition key. Partitioning cannot proceed safely until that constraint work is done.
+
+## Stage two: choose the runtime layout
+
+Declarative method answers how PostgreSQL routes a row. Runtime layout answers how many children you keep attached, how far ahead you premake, and how you prevent rows from landing in the default partition.
+
+Premake-only layout creates the current interval and the next interval, then drains the default partition on a schedule. It is simple and familiar in many codebases. It fails quietly when premake stops or when bounds leave holes: inserts route to default, and attach operations during cutover become fragile. Treat premake-only as a legacy stepping stone, not the long-term target for tables that matter.
+
+Rolling current layout keeps one wide child spanning the current month and many months ahead, then rolls one month at a time into named archive children. It minimizes partition count in the catalog. It demands strict operational discipline: default stays empty, current holds future-dated rows, and monthly roll must not overlap archive bounds. Use only when catalog size is the overriding constraint and the team accepts manual semantics.
+
+Sliding window with three areas is the recommended layout for date-keyed mixed OLTP. Archive holds finalized monthly children before the active window. Current holds a bounded active span, often twelve months, with optional heat-driven splits that carve hot months into dedicated children while gap fillers cover non-hot months. Future is a single open-ended child from the end of the active window to MAXVALUE. Default is mandatory and must trend toward zero rows. A planner reconciles the target tree each maintenance run so ranges do not overlap and do not leave holes.
+
+Extension-managed premake through pg_partman fits plain monthly or id-based series when the hosting environment allows the extension and the table does not need custom current or open fillers. Partman owns premake and retention well. Do not run full custom layout repair on the same parent table without an explicit hybrid contract, or the two maintainers will fight over bounds and drops.
+
+Hypertable-style chunk automation through a time-series extension fits pure metrics and analytics when extension cost and operations are acceptable. It is not a substitute for mixed OLTP where queries ignore time or where composite keys and default-partition maintenance dominate reliability work.
+
+## Stage three: indicators that drive partition creation and sizing
+
+Operators and maintainers watch a small set of indicators. None of them alone decides the design, but together they show when to create children, split buckets, or drop archive.
+
+Watch default partition row count. Sustained rows in default mean the layout is wrong or premake lagged. Default should be a safety net, not a destination. Alert when default is non-zero at the start of a maintenance run.
+
+Watch partition horizon. The upper bound of the latest non-default child should stay comfortably ahead of the maximum insert key. A common operational rule is at least thirty days of headroom for monthly partitions. Shorter horizon means premake or sliding-window rebalance is falling behind.
+
+Watch per-bucket heat inside the active window. When a single month or band exceeds a row threshold on the order of tens to hundreds of thousands of rows, or grows large on disk, dedicate a child for that bucket inside the current zone rather than letting one wide filler absorb all traffic. When a dedicated child stays cold, merge policy may collapse it back, conservatively.
+
+Watch attached child count. Hundreds of partitions increase planner work and schema cache pressure. Prefer a bounded active window and a single future tail over creating many months ahead as separate premade children.
+
+Watch retention policy against archive age. When archive children are older than the policy allows, detach or drop them. Retention belongs in the maintenance story even when layout repair is automated. See [retention.md](retention.md) for detach vs drop, `retention_apply`, and compliance.
+
+Watch query plans for partition pruning on realistic workloads. If pruning does not appear for the queries you care about, the partition key is wrong or the application contract is missing filters. See [partition_landscape.md](partition_landscape.md) for composite primary keys, Rails `query_constraints`, and filter patterns that avoid scanning all partitions.
+
+## Stage four: tools and responsibilities
+
+Separate DDL creation from runtime maintenance.
+
+Use migration helpers such as pg_party or explicit SQL to create the partitioned parent, initial children, indexes, and default partition. At cutover, use a hot-switch migration pattern: shadow partitioned table, minimal premake, atomic rename, then hand off to runtime maintenance. Premake one month ahead at cutover is enough when nightly maintenance owns the window afterward.
+
+Use Partition Gardener for runtime maintenance when you need sliding window layout, default drain last, heat splits inside current, and non-overlapping tail rebalance. Register each parent with partition key, conflict key, template, and thresholds. Run under a single maintainer per table with advisory locking.
+
+Choose maintenance cadence per service, not as a global default. See [Maintenance cadence](#maintenance-cadence) below.
+
+Use pg_partman when the table is a straightforward time or id series, the extension is available, and you do not need three-area layout. Pick one maintainer per table. If partman premakes and gardener also reshapes the same bounds, treat that as a configuration error unless hybrid layout-only mode is documented and implemented. See [tooling_split.md](tooling_split.md).
+
+### Maintenance cadence
+
+Nightly `run!` fits services where layout drift is cheap to repair and row moves are acceptable on a fixed schedule. That is the common case for sliding-window monthly tables with modest move volume and OLTP paths scoped to one or few buckets.
+
+Indicator-driven maintenance fits services where periodic row moves are costly, replica lag is sensitive, or maintenance I/O competes with peak traffic. Those services still need partition layout, but they should not run `apply` on a calendar alone. Run `apply` only when audit indicators cross explicit thresholds (default rows, horizon, heat, gap warnings from [Stage three](#stage-three-indicators-that-drive-partition-creation-and-sizing)). Between runs, rely on premake headroom and application insert discipline to keep default near zero.
+
+Indicator-driven services must treat aggregate snapshots as the hot-path contract, not an optional optimization. Dashboard totals, KPI cards, and cross-period rollups read from bucket-keyed snapshot tables with `computed_at` and drift checks; live `SUM` / `COUNT` across all children stays off request threads. Incremental snapshot updates on writes keep the open bucket current; bounded recompute jobs refresh closed buckets after maintenance moves rows. Without that layer, deferring maintenance forces users onto wide scans that partitioning was meant to avoid. See [partition_landscape.md](partition_landscape.md#aggregates-totals-and-snapshots).
+
+Operational split:
+
+- Nightly or daily: scheduled `run!` after business-date rollover; morning audit confirms invariants.
+- Indicator-driven: scheduled read-only `audit` (hourly or daily); enqueue `run!` for one table when warnings persist or thresholds breach; keep snapshot recompute jobs on their own cadence and rerun affected buckets after high `rows_moved`.
+
+Both cadences use the same Gardener primitives (`plan`, `audit`, `apply`, `run!`). The difference is when `apply` runs and how heavily the application depends on snapshots on hot paths.
+
+Partition Gardener does not replace application query contracts. When child tables must co-locate with a parent on a business date, denormalize that date onto children and require it in filters and joins. The gem does not enforce that contract; migrations and reviews do.
+
+## Reliability invariants
+
+Whatever path the decision flow selects, these invariants stay the same.
+
+Every partitioned parent has a default child attached. Maintenance targets zero rows in default after each run.
+
+Every key value maps to exactly one non-default child after a successful maintenance run. No overlapping bounds and no gaps that force default routing.
+
+Uniqueness constraints include the partition key.
+
+One maintenance owner per parent table per run, guarded by advisory lock.
+
+Retention uses detach or drop of whole children, not bulk delete across the parent, when the goal is to remove old periods.
+
+After creating or reshaping children, analyze the parent when statistics matter for constraint exclusion, especially on large tables.
+
+## Decision flow diagram
+
+```mermaid
+flowchart TD
+  start([Table growth or maintenance pain]) --> size{Large size or retention need?}
+  size -->|no| indexes[Index and query tuning first]
+  size -->|yes| prune{Most queries filter one dimension?}
+  prune -->|no| indexes
+  prune -->|yes| unique{Unique keys include partition key?}
+  unique -->|no| redesign[Redesign PK and unique indexes]
+  redesign --> method
+  unique -->|yes| method{Dominant dimension}
+  method -->|time or date| range[RANGE monthly or yearly]
+  method -->|fixed categories| list[LIST optional subpartition]
+  method -->|even fan-out| hash[HASH modulus fixed at DDL]
+  method -->|branch plus volume| composite[LIST then RANGE or HASH]
+  range --> layout{Runtime layout}
+  layout -->|mixed OLTP default risk| sliding[sliding_window_monthly recommended]
+  layout -->|plain series extension OK| partman[pg_partman premake and retention]
+  layout -->|minimal catalog wide current| rolling[rolling_current_monthly experimental]
+  layout -->|temporary simple cron| premake[premake_monthly legacy migrate away]
+  sliding --> tools[Create: pg_party or SQL. Maintain: Partition Gardener run]
+  partman --> partman_tools[Create: SQL. Maintain: partman only]
+  rolling --> rolling_tools[Create: pg_party or SQL. Maintain: Templates.rolling_current_monthly or custom job]
+  premake --> premake_tools[Create: pg_party or SQL. Maintain: premake template then upgrade]
+```
+
+## Mapping to Partition Gardener
+
+Pick a template from [decision_flow.md](decision_flow.md) and register it with `Registry.register_template` or `Registry.register` unless hosting policy forces pg_partman for that table.
+
+For cutover migrations, include Migration::HotSwitchConcern, resolve partition_config from Registry.hot_switch_partition_config when the table is already registered, and pass months_ahead of one at switch time.
+
+## What this flow does not decide
+
+It does not choose hardware, connection pooling, or read replicas. It does not replace index design. It does not mandate a time-series extension when plain PostgreSQL plus disciplined layout is enough. It does not absolve applications from including the partition key in scopes that must prune, or from shaping UI and APIs so users naturally work inside those bounds.
+
+When in doubt, prefer fewer moving parts: range on a real access key, sliding window maintenance, empty default, one maintainer, and retention by dropping archive children once policy and backups allow.
+
+## Related
+
+- [configuration.md](configuration.md) — registry options and `maintenance_backend`
+- [background_job.md](background_job.md) — schedule `run!` after layout is chosen
+- [tooling_split.md](tooling_split.md) — pg_party, pg_partman, Gardener ownership
+- [partition_landscape.md](partition_landscape.md) — application contract (pruning, UI, snapshots)
+- [cutover.md](cutover.md) — hot-switch checklist
+- [operations.md](operations.md) — post-go-live runbook

data/docs/host_testing.md

@@ -0,0 +1,91 @@
+# Host application testing
+
+How consuming Rails apps (and standalone services) test partitioned tables alongside Partition Gardener. Gem-internal testing lives in [spec/README.md](../spec/README.md).
+
+## Goals
+
+- Prove registry config matches production templates.
+- Prove `plan` / `audit` stay clean on CI data.
+- Catch application queries that omit the partition key before production.
+
+## CI database
+
+Use a real PostgreSQL instance in CI (same major version as production). Docker service or CI-provided Postgres is enough.
+
+Minimal env:
+
+```bash
+export DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/myapp_test
+export INTEGRATION=1  # if reusing gardener integration patterns
+```
+
+Load schema including partitioned parents created by migrations (pg_party or SQL).
+
+## Registry in test
+
+Use the same registry as production in `config/initializers/partition_gardener.rb` or load `config/partition_garden.json` in test with the same template names. Staging should use the same `active_months`, `retention_months`, and `conflict_key` as production unless you intentionally test divergence.
+
+Smoke after migrations:
+
+```ruby
+RSpec.describe "partition registry" do
+  it "audits clean for registered tables" do
+    PartitionGardener::Registry.configs.each do |config|
+      result = PartitionGardener.audit(config[:table_name])
+      expect(result.partitioned).to be(true)
+      expect(result.warnings).to be_empty
+    end
+  end
+end
+```
+
+Run only when PostgreSQL is available; skip in unit-only jobs.
+
+## Application contract specs
+
+Test behavior, not implementation:
+
+- Scoped queries used by controllers return rows only inside the requested window.
+- `create!` with partition key lands queryable row without relying on `default`.
+- Snapshot totals match fixture sums for a single bucket after recompute job.
+
+Avoid asserting exact partition child table names unless testing migration code.
+
+## Gardener maintenance in test
+
+Optional nightly-style test on a disposable table:
+
+```ruby
+PartitionGardener.run!(table_name: "events", dry_run: true)
+PartitionGardener.run!(table_name: "events")
+```
+
+Use a dedicated test parent or truncate children in `around` hooks; do not run full `apply --all` against shared dev databases without isolation.
+
+## Staging checklist
+
+- [ ] Same PostgreSQL major version
+- [ ] Same registry templates and `active_*` spans
+- [ ] `today_resolver` uses app time zone
+- [ ] Maintenance job schedule enabled
+- [ ] Audit cron or monitoring wired ([monitoring.md](monitoring.md))
+- [ ] Cutover playbook exercised once on clone ([cutover.md](cutover.md))
+
+## Staging data with pgsync
+
+[pgsync](https://github.com/ankane/pgsync) copies rows between Postgres databases. Use it to refresh staging with a production-shaped subset before exercising `plan`, `run!`, or cutover drills.
+
+Practices:
+
+- Default destination is localhost unless `to_safe: true` — confirm the target URL before each run.
+- Filter with `where` on the partition key so staging holds realistic month windows without full production volume.
+- Use `--in-batches` on large append-only tables; schedule loads outside Gardener `run!` so rebalance and sync do not contend on the same parent.
+- Apply `data_rules` when copying from production so secrets and PII are redacted in staging.
+
+Gardener does not invoke pgsync. After sync, run `audit` and `plan` on registered tables before enabling nightly maintenance in staging.
+
+## Related
+
+- [application_contract.md](application_contract.md) — what to test
+- [cli.md](cli.md) — local plan and audit
+- [configuration.md](configuration.md) — JSON registry for non-Rails

data/docs/monitoring.md

@@ -0,0 +1,110 @@
+# Monitoring and SLOs
+
+What to measure and alert on for partitioned tables maintained by Partition Gardener. Pair with [operations.md](operations.md) for remediation steps.
+
+## Suggested metrics
+
+Emit from maintenance or audit jobs, CLI audit cron, or a thin wrapper around `PartitionGardener.audit`. Indicator-driven services audit on a schedule and call `run!` only when metrics breach thresholds ([decision_flow.md](decision_flow.md#maintenance-cadence)).
+
+`partition_gardener.default_row_count` — from `audit` per table. Gauge; label `table_name`.
+
+`partition_gardener.horizon_days` — from `audit` per table. Gauge; null if not computable.
+
+`partition_gardener.attached_child_count` — from `audit` per table. Gauge.
+
+`partition_gardener.audit_warning_count` — from `audit` per table. Gauge.
+
+`partition_gardener.run.duration_ms` — from `RunSummary.tables[]`. Histogram per table.
+
+`partition_gardener.run.rows_moved` — from `RunSummary.tables[]`. Counter or gauge per run.
+
+`partition_gardener.run.skipped` — from `RunSummary`. Counter by `skip_reason`.
+
+`partition_gardener.run.failed` — job rescue on `RunFailed`. Counter.
+
+`partition_gardener.snapshot.drift` — application rollup reconcile. Gauge per bucket; see landscape doc.
+
+`partition_gardener.snapshot.stale_seconds` — `now - computed_at` on snapshots. Gauge.
+
+## Alert rules (starting points)
+
+Tune thresholds per table size and bucket grain.
+
+`default_row_count > 0` for 2+ consecutive audit days — warning. Layout or insert contract slipping.
+
+`default_row_count` growing week over week — page. Active mis-routing.
+
+`horizon_days < 30` (monthly buckets) — warning. Premake or rebalance behind.
+
+`horizon_days < 7` — page. Imminent insert routing risk.
+
+`RunFailed` on nightly job — page. At least one table did not complete.
+
+`rows_moved` > baseline × 5 — warning. Large drain or first rebalance; watch I/O and replicas.
+
+`skip_reason = lock_not_acquired` on every table — warning. Duplicate schedulers.
+
+`attached_child_count > 200` — warning. Catalog pressure ([audit](audit_reference.md)).
+
+`snapshot.drift` above threshold — warning. Rollup pipeline bug or move window not reconciled.
+
+`snapshot.stale_seconds` > SLA for closed periods — warning. Background recompute stuck.
+
+## SLO sketches
+
+Document per product; examples:
+
+Default empty: 95% of audit days show `default_row_count = 0` within 24h of any spike.
+
+Horizon: `horizon_days >= 30` for all monthly tables 99% of audit days.
+
+Job success (scheduled maintenance): nightly `run!` completes without `RunFailed` 99.5% of nights.
+
+Layout invariants (indicator-driven maintenance): audit clears breach thresholds within SLA after a triggered `apply`; zero sustained default growth between applies.
+
+Snapshot freshness: closed-month totals `computed_at` within 6h of period close.
+
+## Dashboards
+
+Minimum panels per production partitioned table:
+
+1. Default row count (time series)
+2. Horizon days
+3. Last run `rows_moved` and duration
+4. Audit warning list (table)
+5. Snapshot drift and staleness (application metrics)
+
+## Notifier hook
+
+Wire global `notifier` to your pipeline ([configuration.md](configuration.md)):
+
+```ruby
+PartitionGardener.configure do |config|
+  config.notifier = ->(message_or_error, context: {}) {
+    Metrics.increment("partition_gardener.notify", tags: context)
+    ErrorTracker.notify(message_or_error, extra: context)
+  }
+end
+```
+
+Retention drops and dry-run retention logs also use `notifier`.
+
+## Synthetic checks
+
+Optional daily job (read-only):
+
+```ruby
+PartitionGardener::Registry.each do |config|
+  result = PartitionGardener.audit(config[:table_name])
+  report_to_metrics(result)
+end
+```
+
+Cheaper than full `apply`; catches drift between maintenance runs.
+
+## Related
+
+- [audit_reference.md](audit_reference.md) — field meanings
+- [operations.md](operations.md) — incident response
+- [retention.md](retention.md) — alerts before drop
+- [background_job.md](background_job.md) — job concurrency

data/docs/naming.md

@@ -0,0 +1,71 @@
+# Partition naming catalog
+
+How Gardener names children so operators can read `pg_catalog`, audit output, and `plan` JSON without guessing.
+
+## Tail slots (three-area layout)
+
+Fixed suffixes on the parent table name:
+
+`{table}_default` — catch-all; must trend empty.
+
+`{table}_current` — start of active window.
+
+`{table}_open` — gap filler in current zone.
+
+`{table}_open_N` — extra fillers after heat splits.
+
+`{table}_future` — open-ended tail to MAXVALUE.
+
+`{table}_rebalance_staging` — temporary during tail rebalance.
+
+Defined in `PartitionGardener::Naming`.
+
+## Archive buckets (date range)
+
+Pattern: `{table}_{suffix}` where suffix comes from `DateBucket.partition_name_suffix`:
+
+month — suffix example `events_2026_03`, bounds `[2026-03-01, 2026-04-01)`.
+
+day — suffix example `events_2026_03_15`, bounds one day.
+
+week — suffix example `events_2026_W10`, bounds ISO week.
+
+quarter — suffix example `events_2026_Q1`, bounds calendar quarter.
+
+year — suffix example `events_2026`, bounds calendar year.
+
+Gardener parses archive names back to bucket starts for retention and heat maps. Manual names outside these patterns are ignored for archive retention and may become orphans.
+
+## Integer and hash layouts
+
+- Integer window: band names follow strategy config (`active_id_lo`, band width).
+- Hash branches: remainder or modulus in name per `hash_branches` template.
+- List split: branch label from registry `branches` hash.
+
+See template builders in [configuration.md](configuration.md).
+
+## Composite trees
+
+- LIST parent: branch discriminator in child name.
+- Sub-trees: `{parent}_{branch}` registered as separate gardener tables.
+- Native PostgreSQL sub-partition names must stay consistent with what `expand` registers; gardener plans per registered node ([partition_landscape.md](partition_landscape.md#composite-trees)).
+
+## Hot-switch rename
+
+After `hot_switch_tables`, children rename from `p_events_*` to `events_*` to match the production parent prefix. Plan audits using the post-switch names.
+
+## Drift from manual DDL
+
+Symptoms:
+
+- `partition gap` warnings in audit
+- `plan` shows `reshape` or `drop` on unexpected names
+- Retention skips or targets wrong children
+
+Remediation: prefer `plan` + `apply` over manual attach. If manual children are required, match `FOR VALUES` bounds to planner segments exactly.
+
+## Related
+
+- [operations.md](operations.md) — gap remediation
+- [cutover.md](cutover.md) — shadow `p_` prefix
+- [audit_reference.md](audit_reference.md) — gap messages

data/docs/operations.md

@@ -0,0 +1,131 @@
+# Operations runbook
+
+Day-to-day maintenance for partitioned tables registered with Partition Gardener. Use this page when audit warnings fire, a nightly job fails, or you need to recover a single table without rereading the whole configuration reference.
+
+## Daily rhythm
+
+Two maintenance postures are common. Pick one per service; do not assume every registered table needs the same cadence ([decision_flow.md](decision_flow.md#maintenance-cadence)).
+
+### Scheduled maintenance
+
+1. Nightly `PartitionGardener.run!` (or CLI `apply` in non-Rails environments) after business-date rollover (`today_resolver`).
+2. Morning check: audit JSON for default rows, horizon, and gaps ([audit_reference.md](audit_reference.md)).
+3. Alert on `RunFailed`, sustained default growth, or horizon below threshold ([monitoring.md](monitoring.md)).
+
+### Indicator-driven maintenance
+
+1. Scheduled read-only `audit` (hourly or daily); no `apply` on a fixed calendar unless indicators demand it.
+2. Enqueue `run!` for a table when audit warnings persist: default rows, horizon below threshold, heat above split threshold, or layout gaps.
+3. Same alerts as scheduled maintenance; add snapshot drift and staleness when hot paths read rollups ([partition_landscape.md](partition_landscape.md#aggregates-totals-and-snapshots)).
+4. After `apply`, recompute snapshot buckets affected by high `rows_moved` before treating the incident closed.
+
+Indicator-driven services depend on efficient bucket-keyed snapshots on hot paths so deferred maintenance does not push reporting onto full partition scans.
+
+See [background_job.md](background_job.md) for job concurrency and [retention.md](retention.md) for archive detach and drop policy.
+
+## Commands by situation
+
+Read-only audit: `bundle exec partition_gardener --rails audit TABLE --pretty`
+
+Read-only layout diff: `bundle exec partition_gardener --rails plan TABLE --pretty`
+
+Apply one table: `bundle exec partition_gardener --rails apply --confirm TABLE`
+
+Apply full registry: `bundle exec partition_gardener --rails apply --all`
+
+Ruby dry-run: `PartitionGardener.run!(dry_run: true, table_name: "events")`
+
+Ruby single table: `PartitionGardener.run!(table_name: "events", job_class_name: "Ops")`
+
+Always `plan` before the first `apply` after a registry or template change. In production, prefer the scheduled job; use CLI `apply` for targeted recovery.
+
+## RunSummary fields
+
+`run!` and CLI `apply` return `RunSummary` JSON (`schema_version` 1.0):
+
+`tables[].table_name` — parent table processed.
+
+`tables[].duration_ms` — wall time for that table.
+
+`tables[].plan_signature` — hash of target segments; changes when layout plan changes.
+
+`tables[].rows_moved` — rows moved during default drain and tail rebalance.
+
+`tables[].skipped` — true when the table was not maintained.
+
+`tables[].skip_reason` — e.g. `lock_not_acquired`, `not_partitioned`, `pg_partman`.
+
+`errors` — messages collected when `continue_on_error` is true; run still raises `RunFailed` at end if non-empty.
+
+Interpretation:
+
+- `lock_not_acquired` — another worker holds the advisory lock; usually harmless if one job owns maintenance. Investigate duplicate cron or overlapping deploy hooks.
+- High `rows_moved` after a quiet period — default drain catching up, or first run after cutover. Expect elevated I/O; watch replica lag ([application_contract.md](application_contract.md)).
+- `errors` non-empty — at least one table failed; other tables may have completed. Fix the failing table, then rerun that table only.
+
+## Audit warnings to actions
+
+Full catalog: [audit_reference.md](audit_reference.md). Quick map:
+
+default partition has N rows (N > 0) — likely inserts outside bounds, premake lag, or wrong partition key on writes. Action: `plan` then `apply`; fix application inserts; check horizon.
+
+default partition is missing — incomplete creation migration. Action: create default child; never leave parent without default on RANGE layouts that require it.
+
+partition horizon is X days ahead (below 30) — premake or sliding-window rebalance behind. Action: `apply`; verify `active_months` / premake settings.
+
+partition gap: uncovered range between … — overlapping manual DDL or interrupted rebalance. Action: `plan` to see target; `apply`; avoid hand-attaching overlapping children.
+
+no attached tail partition extends to MAXVALUE — missing `_future` or open tail. Action: `apply`; compare `attached_segments` vs `target_segments` in plan.
+
+attached child count is N (high catalog pressure) — too many archive months attached or manual sprawl. Action: tighten `active_months`; enable `retention_months`; review [naming.md](naming.md) for orphan children.
+
+table is not a partitioned table — registry typo or wrong connection. Action: fix registry; point `connection_resolver` at correct database.
+
+## Failed or partial runs
+
+Gardener persists checkpoints in `partition_gardener_run_records` when `run_record_enabled` is true (default).
+
+1. Read `errors` and notifier context (`table_name`, `action`).
+2. `audit TABLE` — confirm default count and gaps unchanged or worse.
+3. `plan TABLE` — if `changed` is true, layout still needs work.
+4. Retry `run!(table_name: TABLE)` — incremental rebalance resumes when `plan_signature` matches the stored record.
+5. If a staging partition `TABLE_rebalance_staging` exists and blocks progress, inspect row count and consult gem issues; orphaned staging outside a matching `plan_signature` is cleared on the next full apply.
+
+Set `continue_on_error: false` only when you want the job to stop on the first table failure.
+
+## Retention during operations
+
+When `retention_months` is set, gardener detaches (and optionally drops) archive children older than the cutoff after layout work. See [retention.md](retention.md) for legal hold, `retention_keep_table`, and backup checks before drop.
+
+`retention_detach_concurrently: true` reduces lock duration on detach; requires PostgreSQL 14+ and no long transactions holding the partition.
+
+## Index review after large layout changes
+
+When `rows_moved` is high after rebalance, heat splits, or template upgrades, query plans may need new indexes on hot children. Review manually or run [Dexter](https://github.com/ankane/dexter) against recent workload ([related_postgres_tooling.md](related_postgres_tooling.md)). Gardener does not create indexes; `plan` / `apply` only change partition bounds and row placement.
+
+## Sharded registries
+
+Run maintenance per shard connection:
+
+```ruby
+ShardRecord.connected_to_all_shards do
+  PartitionGardener.run!(job_class_name: self.class.name)
+end
+```
+
+Or set `connection_resolver` on a shard-specific registry load. Audit and apply are per connection; there is no cross-shard summary in one CLI invocation.
+
+## What not to do in incidents
+
+- Do not hand-`DROP` archive children without retention policy and backup review.
+- Do not attach overlapping RANGE children to fix gaps without reading `plan` output.
+- Do not run two full `apply --all` jobs concurrently without concurrency limits.
+- Do not disable default drain to “fix” slowness; fix bounds and inserts instead.
+
+## Related
+
+- [audit_reference.md](audit_reference.md) — warning and plan field reference
+- [monitoring.md](monitoring.md) — metrics and alerts
+- [cutover.md](cutover.md) — first-time migration and rollback
+- [configuration.md](configuration.md) — registry options
+- [cli.md](cli.md) — CLI flags