partition_gardener 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9dc13f2d2bdae3ecc6cf8e9d66a27f836c1cebbb06bdfd84452e4698e5cb8c63
+  data.tar.gz: e60370a277cdcd06b9d2376f4d73169ac29792ed9e7f150a6177d1a1e5703c92
+SHA512:
+  metadata.gz: 70d5dabf55e8e6b207768233e2f4f154784531ba35cac9f9731cae76141f81252810acd9bb9fded3c9547c1b60c207be7ad0cf5baca47a950869fa0dd6463ea3
+  data.tar.gz: 23e10104588d5878c59bb25c3d3116d2cf9ea25793c13dff785a0c90b57f545889ec87bc6b56c5a480a1defdf3b367c0de3ec698ef0b85a1953c9c654c55f64e

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# CHANGELOG
+
+## 0.3.0 (2026-07-08)
+
+- Remove `suggest_template`, `recommend`, and register-time layout reliability warnings
+- Add structured branch predicates for list-split layouts so operators declare column, operator, and value instead of raw SQL fragments
+- Add shorthand list-branch filters from partition key column plus branch value at registration time
+- Document materialized view limits, manual per-slice patterns, and rollup table alternatives in the partition landscape guide
+- Clarify Gardener maintenance scope applies to declarative partitioned tables, not materialized views
+
+## 0.2.0 (2026-07-06)
+
+- Add configuration, background job, and CLI guides under `docs/`
+- Add `partition_gardener` CLI with `plan`, `audit`, and `apply` for dry-run planning, layout audit, and maintenance
+- Add dry-run plan reports with gap detection and JSON schema export
+- Add hot-switch migration helpers for zero-downtime cutover to partitioned tables
+- Add layout recommendations for date partition keys
+- Add per-table advisory locks during maintenance runs
+- Add `continue_on_error` so one failing table does not block the rest
+- Add run summaries with per-table duration, plan signature, and rows moved
+- Add sliding-window retention policies with optional concurrent detach
+- Add incremental rebalance and resume checkpoints after partial rebalance failure
+- Add per-table statement timeouts during maintenance
+- Add conflict-index verification before row moves
+- Add durable run records when ActiveRecord is available
+- Fix default advisory lock to transaction-scoped try-lock and skip locked tables
+- Fix hash partition layouts to omit unsupported default partitions
+- Fix hot-switch delta sync when there are no updatable columns
+- Fix batch row moves to avoid `ON CONFLICT` stalls during rebalance
+
+## 0.1.0 (2026-07-05)
+
+- Initial release of PostgreSQL partition lifecycle maintenance
+- Add templates for sliding-window monthly, calendar year, integer window, list split, composite, and hash layouts
+- Add injectable notifier, connection, statement timeout, and today resolver
+- Add Rails railtie for ActiveRecord connection defaults

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kisko Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,203 @@
+# Partition Gardener
+
+[![Gem Version](https://badge.fury.io/rb/partition_gardener.svg)](https://badge.fury.io/rb/partition_gardener) [![Test Status](https://github.com/amkisko/partition_gardener.rb/actions/workflows/test.yml/badge.svg)](https://github.com/amkisko/partition_gardener.rb/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amkisko/partition_gardener.rb/graph/badge.svg)](https://codecov.io/gh/amkisko/partition_gardener.rb)
+
+PostgreSQL partition lifecycle: archive, current, and future zones, heat-driven splits inside the active window, cursor-based rebalance, mandatory default drain, and hot-switch migration helpers. Rails-integrated by default; works standalone with `pg` and a JSON registry.
+
+## Requirements
+
+- Ruby >= 3.2
+- PostgreSQL with declarative partitioning
+- `pg` gem (runtime dependency)
+- Rails >= 7.1 optional — railtie loads when Rails is present and sets Active Record connection plus `Time.zone.today`
+
+Complements migration gems (e.g. [pg_party](https://github.com/rkrage/pg_party)) — use those for creation DDL; use this gem for runtime maintenance (scheduled or indicator-driven) and cutover migrations. See [docs/related_postgres_tooling.md](docs/related_postgres_tooling.md) for how Gardener pairs with [PgHero](https://github.com/ankane/pghero), [Dexter](https://github.com/ankane/dexter), [pgsync](https://github.com/ankane/pgsync), and [pgslice](https://github.com/ankane/pgslice).
+
+## Documentation
+
+### Choosing and configuring
+
+- [docs/decision_flow.md](docs/decision_flow.md) — when to partition, layout, and method choices
+- [docs/partition_landscape.md](docs/partition_landscape.md) — templates, Rails sharding, pruning, UI, aggregate snapshots, materialized views
+- [docs/configuration.md](docs/configuration.md) — global config, registry, per-table options, JSON import
+- [docs/tooling_split.md](docs/tooling_split.md) — pg_party vs pg_partman vs Gardener
+- [docs/related_postgres_tooling.md](docs/related_postgres_tooling.md) — PgHero, Dexter, pgsync, pgslice vs Gardener
+- [docs/pg_party_recipe.md](docs/pg_party_recipe.md) — creation DDL with pg_party
+
+### Operations
+
+- [docs/operations.md](docs/operations.md) — runbook, incidents, RunSummary
+- [docs/audit_reference.md](docs/audit_reference.md) — audit and plan warning catalog
+- [docs/monitoring.md](docs/monitoring.md) — metrics, alerts, SLOs
+- [docs/retention.md](docs/retention.md) — detach, drop, compliance, legal hold
+- [docs/background_job.md](docs/background_job.md) — host job pattern, concurrency, scheduling
+- [docs/cli.md](docs/cli.md) — plan, audit, and apply commands
+
+### Application and migration
+
+- [docs/cutover.md](docs/cutover.md) — hot-switch playbook and template upgrades
+- [docs/application_contract.md](docs/application_contract.md) — writes, moves, bulk load, replicas
+- [docs/naming.md](docs/naming.md) — child partition naming catalog
+- [docs/host_testing.md](docs/host_testing.md) — CI and staging for host apps
+
+### Schemas
+
+- [docs/schemas/](docs/schemas/) — JSON schemas for registry and plan reports
+
+## Quick start
+
+```ruby
+# Gemfile
+gem "partition_gardener"
+```
+
+```ruby
+# config/initializers/partition_gardener.rb — see docs/configuration.md for all options
+PartitionGardener.configure do |config|
+  config.notifier = ->(message, context: {}) { Rails.logger.info(message) }
+  config.today_resolver = -> { Time.zone.today }
+end
+
+PartitionGardener::Registry.register_template(
+  :sliding_window_monthly,
+  table_name: "events",
+  partition_key_column: "occurred_on",
+  conflict_key: %w[id occurred_on],
+  active_months: 12
+)
+```
+
+```ruby
+# app/jobs/partition_maintenance_job.rb — see docs/background_job.md
+class PartitionMaintenanceJob < ApplicationJob
+  def perform
+    PartitionGardener.run!(job_class_name: self.class.name)
+  end
+end
+```
+
+```bash
+# Dry-run plan from the app directory
+bundle exec partition_gardener --rails plan events --pretty
+```
+
+### Standalone (no Rails)
+
+Set `DATABASE_URL` and point the CLI at a JSON registry:
+
+```bash
+export DATABASE_URL=postgres://postgres@127.0.0.1:5432/mydb
+bundle exec partition_gardener --registry config/partition_garden.json plan events --pretty
+```
+
+Or configure in Ruby:
+
+```ruby
+PartitionGardener.configure do |config|
+  config.connection_resolver = -> { PartitionGardener::PgConnection.connect(ENV.fetch("DATABASE_URL")) }
+  config.today_resolver = -> { Date.today }
+end
+PartitionGardener::ConfigDocument.load_registry_file!("config/partition_garden.json")
+PartitionGardener.run!
+```
+
+## Default layout
+
+Default layout: monthly sliding window (`register_template :sliding_window_monthly` in the Rails example above). Three-area layout with planner-enforced non-overlapping ranges, default drained last, and keyset moves on `(partition_key, conflict_key)`.
+
+See [docs/decision_flow.md](docs/decision_flow.md) for when to pick other templates.
+
+## Templates
+
+`Templates.sliding_window_monthly` (layout `:sliding_window`, bucket `:month`) — `RANGE (date)` monthly time-series.
+
+`Templates.sliding_window_daily` (bucket `:day`) — daily buckets for short retention telemetry.
+
+`Templates.sliding_window_weekly` (bucket `:week`) — ISO-week buckets.
+
+`Templates.sliding_window_quarterly` (bucket `:quarter`) — calendar-quarter buckets.
+
+`Templates.calendar_year` (layout `:calendar_year`) — `RANGE (date)` yearly buckets.
+
+`Templates.rolling_current_monthly` (layout `:rolling_current`) — monthly sliding window without heat splits.
+
+`Templates.integer_window` (layout `:integer_window`) — `RANGE (bigint)` id bands.
+
+`Templates.list_split` (layout `:list_split`) — fixed `LIST` branches.
+
+`Templates.composite_list_hash` (layout `:composite`) — LIST parent plus HASH sub-trees.
+
+`Templates.composite_list_range` / `Templates.list_range` — LIST parent plus RANGE sliding-window sub-trees.
+
+`Templates.composite_range_hash` — RANGE parent plus HASH child tables.
+
+`Templates.composite_range_list` — RANGE parent plus LIST child tables.
+
+`Templates.hash_branches` (layout `:hash_branches`) — `HASH` remainders.
+
+`Templates.premake_monthly` (layout `:premake_monthly`) — cron-style premake bridge; migrate to sliding window.
+
+See [docs/partition_landscape.md](docs/partition_landscape.md) for the template catalog, Rails sharding, composite keys, partition pruning, UI and product surfaces, aggregate snapshots, and materialized view limits. Operations: [operations.md](docs/operations.md), [cutover.md](docs/cutover.md), [monitoring.md](docs/monitoring.md).
+
+## Hot-switch migrations
+
+`PartitionGardener::Migration::HotSwitchConcern` (alias `HotSwitchPartitionedTable`) consolidates cutover migration helpers.
+
+```ruby
+class PartitionEventsHotSwitch < ActiveRecord::Migration[8.0]
+  include PartitionGardener::Migration::HotSwitchConcern
+
+  HOT_SWITCH_CONFIG = {
+    current_table: "events",
+    partitioned_table: "p_events",
+    partition_key_column: "occurred_on",
+    conflict_key: %w[id occurred_on],
+    partition_config: PartitionGardener::Registry.hot_switch_partition_config("events")
+  }.freeze
+
+  def up
+    ensure_future_partitions_exist(months_ahead: 1)
+    hot_switch_tables
+  end
+end
+```
+
+`partition_config` may also be an inline hash for tables not yet registered.
+
+## Runtime guarantees
+
+- Per-table advisory lock during maintenance (`hashtext` namespace plus table name)
+- `continue_on_error: true` by default — one failing table does not block others (`PartitionGardener::RunFailed` aggregates errors)
+- Batch moves use composite keyset cursors and delete source rows by batch keys
+- `run!` returns `RunSummary` with per-table duration, `plan_signature`, and `rows_moved`
+- `maintenance_backend: :pg_partman` skips gardener for partman-owned tables
+
+## Tests
+
+App-agnostic PostgreSQL integration specs live under `spec/integration/`. CI and local full-suite runs use [polyrun](https://github.com/amkisko/polyrun) to shard specs across parallel workers (each worker uses its own PostgreSQL database when `DATABASE_URL` is set).
+
+```bash
+# Full suite (unit + integration; requires PostgreSQL)
+make test
+
+# Same as make test
+INTEGRATION=1 DATABASE_URL=postgres://postgres@127.0.0.1:5432/partition_gardener_test ./bin/polyrun parallel-rspec --workers 5
+
+# Unit specs only
+bundle exec rspec --exclude-pattern "spec/integration/**/*_spec.rb"
+
+# Integration only (requires PostgreSQL)
+INTEGRATION=1 DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/partition_gardener_test bundle exec rake spec:integration
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Sponsors
+
+Sponsored by [Kisko Labs](https://www.kiskolabs.com).
+
+<a href="https://www.kiskolabs.com">
+  <img src="kisko.svg" width="200" alt="Sponsored by Kisko Labs" />
+</a>

data/SECURITY.md

@@ -0,0 +1,27 @@
+# Security
+
+## Reporting a vulnerability
+
+Do not open a public GitHub issue for security vulnerabilities.
+
+Email security details to: security@kiskolabs.com
+
+Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+
+### Response timeline
+
+- We will acknowledge receipt of your report
+- We will provide an initial assessment
+- We will keep you informed of our progress and resolution timeline
+
+### Disclosure policy
+
+- We will work with you to understand and resolve the issue
+- We will credit you for the discovery (unless you prefer to remain anonymous)
+- We will publish a security advisory after the vulnerability is patched
+- We will coordinate public disclosure with you
+
+## Automation security
+
+- Context isolation. It is strictly forbidden to include production credentials, API keys, or personally identifiable information in prompts sent to third-party LLMs or automation services.
+- Supply chain. All automated dependencies must be verified.

data/docs/THIRD_PARTY_LICENSE_MANIFEST.tsv

@@ -0,0 +1,60 @@
+bundle	gem	version	licenses
+root	activemodel	8.1.3	MIT
+root	activerecord	8.1.3	MIT
+root	activesupport	8.1.3	MIT
+root	appraisal	2.5.0	MIT
+root	ast	2.4.3	MIT
+root	base64	0.3.0	Ruby|BSD-2-Clause
+root	bigdecimal	4.1.2	Ruby|BSD-2-Clause
+root	bundler	4.0.15	MIT
+root	concurrent-ruby	1.3.7	MIT
+root	connection_pool	3.0.2	MIT
+root	diff-lcs	1.6.2	MIT|Artistic-1.0-Perl|GPL-2.0-or-later
+root	drb	2.2.3	Ruby|BSD-2-Clause
+root	i18n	1.15.2	MIT
+root	json	2.20.0	Ruby
+root	language_server-protocol	3.17.0.6	MIT
+root	lint_roller	1.1.0	MIT
+root	logger	1.7.0	Ruby|BSD-2-Clause
+root	minitest	6.0.6	MIT
+root	parallel	2.1.0	MIT
+root	parser	3.3.11.1	MIT
+root	partition_gardener	0.3.0	MIT
+root	pg	1.6.3	BSD-2-Clause
+root	polyrun	1.5.0	MIT
+root	prism	1.9.0	MIT
+root	racc	1.8.1	Ruby|BSD-2-Clause
+root	rack	3.2.6	MIT
+root	rainbow	3.1.1	MIT
+root	rake	13.4.2	MIT
+root	rbs	3.10.4	BSD-2-Clause|Ruby
+root	regexp_parser	2.12.0	MIT
+root	rspec	3.13.2	MIT
+root	rspec-core	3.13.6	MIT
+root	rspec-expectations	3.13.5	MIT
+root	rspec-mocks	3.13.8	MIT
+root	rspec-support	3.13.7	MIT
+root	rspec_junit_formatter	0.6.0	MIT
+root	rubocop	1.87.0	MIT
+root	rubocop-ast	1.50.0	MIT
+root	rubocop-capybara	2.23.0	MIT
+root	rubocop-factory_bot	2.28.0	MIT
+root	rubocop-performance	1.26.1	MIT
+root	rubocop-rails	2.34.3	MIT
+root	rubocop-rspec	3.10.2	MIT
+root	rubocop-rspec_rails	2.32.0	MIT
+root	rubocop-thread_safety	0.7.3	MIT
+root	ruby-progressbar	1.13.0	MIT
+root	securerandom	0.4.1	Ruby|BSD-2-Clause
+root	standard	1.55.0	
+root	standard-custom	1.0.2	MIT
+root	standard-performance	1.9.0	MIT
+root	standard-rails	1.6.0	MIT
+root	standard-rspec	0.5.0	MIT
+root	thor	1.5.0	MIT
+root	timeout	0.6.1	Ruby|BSD-2-Clause
+root	tsort	0.2.0	Ruby|BSD-2-Clause
+root	tzinfo	2.0.6	MIT
+root	unicode-display_width	3.2.0	MIT
+root	unicode-emoji	4.2.0	MIT
+root	uri	1.1.1	Ruby|BSD-2-Clause

data/docs/application_contract.md

@@ -0,0 +1,82 @@
+# Application contract
+
+How host applications should behave around partitioned tables: queries, writes, maintenance side effects, bulk load, and replicas. For UI scoping and aggregate snapshots see [partition_landscape.md](partition_landscape.md). For operator runbooks see [operations.md](operations.md).
+
+## Query and write basics
+
+- Hot-path reads and writes include the partition key in plain predicates (no wrappers on the key column).
+- `conflict_key` columns match the parent unique index; updates and deletes use `query_constraints` when the logical id is not globally unique ([partition_landscape.md](partition_landscape.md#rails-application-contract)).
+- Inserts supply a routable partition key value so rows land in named children, not only in `default`.
+
+## During maintenance (row moves)
+
+Maintenance runs move rows in batches keyed by `(partition_key, conflict_key)`:
+
+- Moves are delete-from-source, insert-into-target within transactions; logical row identity is preserved when `conflict_key` is stable.
+- Row-level triggers and callbacks fire per batch; prefer idempotent side effects or defer heavy work to jobs keyed by `conflict_key`.
+- Counter caches and Rails `counter_cache` on associations may drift during moves; use snapshots or reconcile after maintenance ([partition_landscape.md](partition_landscape.md#aggregates-totals-and-snapshots)).
+- Outbox and change-data-capture streams may emit move pairs; consumers should treat `(id, partition_key)` as identity.
+
+After a run with high `rows_moved`, schedule snapshot recompute for affected buckets and watch replica lag.
+
+## Insert routing failures
+
+Row in `default` — key outside attached bounds or horizon lag. Application response: fix key; gardener drains default on next run.
+
+PostgreSQL routing error — no child accepts key. Application response: `apply` to extend horizon; never silence without ops review.
+
+Duplicate key across children — overlapping manual DDL. Application response: stop writes; `plan` / `apply`; remove overlapping attach.
+
+Applications should not catch routing errors and retry without the partition key.
+
+## Bulk import and backfill
+
+- Chunk `COPY` or `insert_all` by bucket window within partition bounds (month, week, day).
+- Set partition key explicitly on every row; do not rely on defaults that omit the key.
+- Run imports during low traffic or against a shadow table during cutover ([cutover.md](cutover.md)).
+- Disable or throttle per-row callbacks on mass load; run bucket snapshot recompute after import completes.
+
+## Read replicas
+
+- Row moves generate write load on the primary; replicas may lag during large `rows_moved` nights.
+- Do not run reporting aggregates on replicas that must be strictly current during maintenance windows; use snapshots or primary with bounded windows.
+- Logical replication of partitioned parents replicates to the parent; child layout is visible on subscribers. Coordinate major layout changes with replication monitoring.
+
+## Foreign keys and references
+
+PostgreSQL limits foreign keys referencing partitioned tables and FKs across partition boundaries. Prefer:
+
+- Application-level integrity for cross-table references into partitioned facts.
+- Composite references that include the partition key when FKs are required.
+- Document any FK from partitioned child to dimension table in migration reviews.
+
+Gardener does not add or remove FKs during maintenance.
+
+## Sharded applications
+
+Compose Rails shard routing with per-shard partition filters:
+
+```ruby
+ApplicationRecord.connected_to(shard: :tenant_a) do
+  Event.in_window(month_range).where(workspace_id: workspace.id)
+end
+```
+
+Maintenance runs per shard; registry JSON may differ per shard only if layouts differ (unusual).
+
+## Admin and operator surfaces
+
+- Default filters: current month or selected tenant, not all history.
+- Global id search is an advanced, slow path; require date or tenant hint.
+- Export flows chunk by bucket; show progress per period.
+- Totals read from snapshot tables with `computed_at`, not live `SUM` across all children or a stale materialized view over the full fact table ([partition_landscape.md](partition_landscape.md#materialized-views)).
+
+## Testing expectations
+
+See [host_testing.md](host_testing.md) for CI registry fixtures and integration smoke tests.
+
+## Related
+
+- [partition_landscape.md](partition_landscape.md) — pruning, UI, snapshots
+- [cutover.md](cutover.md) — backfill and switch
+- [naming.md](naming.md) — child table names

data/docs/audit_reference.md

@@ -0,0 +1,125 @@
+# Audit and plan reference
+
+Human-readable catalog for `PartitionGardener.audit`, `PartitionGardener.plan`, CLI `audit` / `plan`, and `RunSummary` output. JSON schemas: [plan_report.schema.json](schemas/plan_report.schema.json), [partition_garden.schema.json](schemas/partition_garden.schema.json).
+
+## Audit result (`schema_version` 1.0)
+
+`table_name` (string) — parent table.
+
+`partitioned` (boolean) — declarative parent exists.
+
+`default_row_count` (integer) — rows in `{table}_default`.
+
+`attached_child_count` (integer) — attached children including default.
+
+`horizon_days` (integer or null) — days from `today` to latest finite upper bound among children.
+
+`gaps` (array) — structural range gaps in tail layout.
+
+`warnings` (array of string) — human-readable issues.
+
+Horizon warning threshold: 30 days (`Audit::HORIZON_WARNING_DAYS`). High child count warning: more than 200 attached children.
+
+## Audit warning catalog
+
+`{table} is not a partitioned table` — parent missing or not partitioned. Fix migration; check `connection_resolver`.
+
+`default partition {name} has {n} rows` — rows routed to default. Fix inserts; run `apply` to drain.
+
+`default partition {name} is missing` — no default child. Add default partition for layouts that require it.
+
+`partition horizon is {d} days ahead (below 30)` — future bound too close. Run `apply`; check premake / `active_*`.
+
+`attached child count is {n} (high catalog pressure)` — too many children. Retention; reduce `active_months`; remove orphans.
+
+`partition gap: uncovered range between {a} and {b} ({from}..{to})` — hole between adjacent tail segments. `plan` then `apply`; remove overlapping manual DDL.
+
+`partition gap: no attached tail partition extends to MAXVALUE` — missing future/open tail. `apply` to attach `_future`.
+
+Gap objects include `range_start`, `range_end`, and `message`.
+
+## Plan report
+
+`schema_version` — `"1.0"`.
+
+`table_name` — parent.
+
+`layout` — registry layout symbol (e.g. `sliding_window`).
+
+`changed` — `true` when operations would mutate catalog or move rows.
+
+`plan_signature` — stable hash of target segments; stored in run records for resume.
+
+`target_segments` — desired segment list (`name`, `range_start`, `range_end`, `kind`).
+
+`attached_segments` — current catalog segments.
+
+`operations` — planned steps: `keep`, `create`, `reshape`, `drop`.
+
+`gaps` — same structure as audit gaps on attached tail.
+
+`hot_buckets` — buckets exceeding heat threshold inside active window.
+
+Use `changed: false` to skip apply when only verifying drift.
+
+### Operation actions
+
+`keep` — segment already matches target.
+
+`create` — new child attach.
+
+`reshape` — bound or name change; may move rows.
+
+`drop` — detach or drop child (retention or layout).
+
+## RunSummary (apply / run!)
+
+`schema_version` — `"1.0"`.
+
+`tables` — array of per-table metrics objects.
+
+`errors` — string messages; run raises `RunFailed` if non-empty (with default `continue_on_error`).
+
+Per-table metrics (`RunMetrics#to_h`):
+
+`table_name` — parent.
+
+`duration_ms` — elapsed milliseconds.
+
+`plan_signature` — signature applied (null if skipped early).
+
+`rows_moved` — rows relocated by maintenance.
+
+`skipped` — boolean.
+
+`skip_reason` — `lock_not_acquired`, etc.
+
+## Run record table
+
+When `run_record_enabled`, PostgreSQL table `partition_gardener_run_records` stores:
+
+`table_name` — parent.
+
+`phase` — rebalance phase checkpoint.
+
+`plan_signature` — resume when matches current plan.
+
+`staging_row_count` — progress through staging partition.
+
+`updated_at` — last checkpoint time.
+
+Disable globally or per table if you do not want checkpoint storage ([configuration.md](configuration.md)).
+
+## CLI mapping
+
+`audit TABLE` — `PartitionGardener.audit(TABLE)`.
+
+`plan TABLE` — `PartitionGardener.plan(table_name: TABLE)`.
+
+`apply --confirm TABLE` — `PartitionGardener.run!(table_name: TABLE)`.
+
+## Related
+
+- [operations.md](operations.md) — remediation workflows
+- [monitoring.md](monitoring.md) — metrics from these fields
+- [naming.md](naming.md) — segment names in output