partition_gardener 0.3.0

data/docs/background_job.md

@@ -0,0 +1,161 @@
+# Background job integration
+
+Partition Gardener does not ship an Active Job class, queue adapter, or cron schedule. The gem exposes `PartitionGardener.run!`; the host application owns scheduling, queue choice, and concurrency policy.
+
+## Minimal job
+
+```ruby
+class PartitionMaintenanceJob < ApplicationJob
+  queue_as :cleaners
+
+  def perform
+    PartitionGardener.run!(job_class_name: self.class.name)
+  end
+end
+```
+
+Pass `job_class_name:` so notifier context and run metadata identify the host job (for example in Sentry or structured logs).
+
+## Recommended host-app practices
+
+### One maintainer at a time per table
+
+Gardener acquires a per-table PostgreSQL advisory lock during `run!`. A second worker skips that table with `lock_not_acquired` rather than blocking forever.
+
+Still limit full maintenance runs to one concurrent job for the whole registry when possible. Two jobs iterating all tables waste work and inflate log noise even when locks serialize per table.
+
+Example with Good Job:
+
+```ruby
+class PartitionMaintenanceJob < ApplicationJob
+  queue_as :cleaners
+
+  include GoodJob::ActiveJobExtensions::Concurrency
+
+  good_job_control_concurrency_with(
+    key: -> { self.class.name },
+    total_limit: 1
+  )
+
+  def perform
+    PartitionGardener.run!(job_class_name: self.class.name)
+  end
+end
+```
+
+Sidekiq, Solid Queue, and other adapters have similar uniqueness or concurrency controls — use whatever matches the host app.
+
+### Schedule
+
+Sliding-window maintenance is designed for periodic runs, not per-insert work. How often to call `run!` depends on service load and move tolerance.
+
+#### Scheduled maintenance (default)
+
+Run nightly or off-peak when row moves on a fixed cadence are acceptable and audit usually stays clean between runs.
+
+Typical cadence:
+
+- Production: once per day after the business-date rollover the app uses (`today_resolver`)
+- Staging: same schedule to catch config drift before production
+- After cutover: run manually or on the next schedule slot; verify default partition row count reaches zero
+
+#### Indicator-driven maintenance
+
+Some services should not run maintenance nightly. Defer `run!` until audit indicators clearly show need: non-zero default, horizon below threshold, heat split warranted, or gap warnings. Schedule read-only `audit` on a fixed cadence; enqueue `apply` / `run!` only when warnings persist or breach operator thresholds ([monitoring.md](monitoring.md), [decision_flow.md](decision_flow.md#maintenance-cadence)).
+
+Services on this cadence should serve hot-path totals and rollups from bucket-keyed snapshot tables, not live aggregates across all partitions ([partition_landscape.md](partition_landscape.md#aggregates-totals-and-snapshots)). Snapshot freshness and drift checks become part of the maintenance story alongside layout audit.
+
+Example gate job:
+
+```ruby
+class PartitionAuditJob < ApplicationJob
+  queue_as :cleaners
+
+  def perform
+    PartitionGardener::Registry.each do |config|
+      result = PartitionGardener.audit(config[:table_name])
+      next unless needs_maintenance?(result)
+
+      PartitionMaintenanceJob.perform_later(table_name: config[:table_name])
+    end
+  end
+
+  private
+
+  def needs_maintenance?(audit_result)
+    audit_result.warnings.any? { |warning| threshold_breached?(warning) }
+  end
+end
+```
+
+Tune `needs_maintenance?` to your SLOs; do not run `apply` on a single transient spike without a second audit or sustained breach.
+
+Cron, Good Job cron, or an external scheduler (Kubernetes CronJob, systemd timer) are all valid. The gem does not prescribe one.
+
+### Statement timeouts
+
+Wrap maintenance in the host database timeout helper via global config:
+
+```ruby
+PartitionGardener.configure do |config|
+  config.statement_timeout_wrapper = ->(timeout, &block) {
+    DatabaseTimeout.statement_timeout(timeout, &block)
+  }
+end
+```
+
+Per-table overrides: `statement_timeout: 10.minutes` on the registry entry.
+
+### Error handling
+
+Default `continue_on_error: true` finishes other tables when one fails, then raises `PartitionGardener::RunFailed` with all errors. The job should retry or alert on `RunFailed`.
+
+To fail fast on the first table error:
+
+```ruby
+PartitionGardener.run!(continue_on_error: false, job_class_name: self.class.name)
+```
+
+Notifier hook — wire to your reporting pipeline:
+
+```ruby
+PartitionGardener.configure do |config|
+  config.notifier = ->(message_or_error, context: {}) {
+    ActionReporter.notify(message_or_error, context: context)
+  }
+end
+```
+
+### Single-table runs
+
+For targeted recovery after an incident:
+
+```ruby
+PartitionGardener.run!(table_name: "audits", job_class_name: self.class.name)
+```
+
+The CLI `apply` command accepts one table by default; pass `--all` for the full registry ([cli.md](cli.md)).
+
+## What the job should not do
+
+- Do not reimplement premake, default drain, or tail rebalance in the job — call `run!` only.
+- Do not register the same parent with both partman and gardener unless using `hybrid_layout_only` intentionally ([tooling_split.md](tooling_split.md)).
+- Do not run maintenance inside request cycles.
+
+## Alternatives to a job
+
+`bundle exec partition_gardener --rails apply TABLE` — manual ops, CI smoke, one-off recovery.
+
+`PartitionGardener.run!(dry_run: true)` — pre-deploy plan review.
+
+`PartitionGardener.audit("audits")` — read-only layout audit without writes ([audit_reference.md](audit_reference.md)).
+
+## Rollup and snapshot jobs
+
+Dashboard totals and cross-period aggregates should refresh in separate background jobs, bucketed like partitions ([partition_landscape.md](partition_landscape.md#aggregates-totals-and-snapshots)). Materialized views are not a substitute for bucket-keyed snapshot tables on hot paths ([materialized views](partition_landscape.md#materialized-views)). Schedule rollup recompute after maintenance when `rows_moved` is high, or on a fixed cadence with drift checks ([monitoring.md](monitoring.md)).
+
+## Related
+
+- [configuration.md](configuration.md) — global and per-table options
+- [cli.md](cli.md) — plan, audit, apply without enqueueing a job
+- [operations.md](operations.md) — incident runbook

data/docs/cli.md

@@ -0,0 +1,71 @@
+# CLI
+
+The `partition_gardener` executable plans, audits, and applies maintenance without enqueueing a background job.
+
+```bash
+bundle exec partition_gardener --rails plan audits
+bundle exec partition_gardener --registry config/partition_garden.json audit --all
+bundle exec partition_gardener --rails apply --confirm audits
+```
+
+## Commands
+
+`plan` — read-only. Outputs the target layout diff as JSON ([plan_report.schema.json](schemas/plan_report.schema.json)).
+
+`audit` — read-only. Outputs layout audit warnings as JSON (default rows, gaps, horizon).
+
+`apply` — writes data. Runs `PartitionGardener.run!` and prints `RunSummary` JSON. Requires `--confirm`.
+
+## Options
+
+`--rails` — load registry from the host Rails environment (`config/environment.rb`).
+
+`--registry PATH` — load registry from a JSON file ([configuration.md](configuration.md#json-registry-files)).
+
+`--table NAME` — table name (default: first positional argument after the command).
+
+`--all` — all registered tables (plan and audit only; apply runs full registry when omitted with `--all`).
+
+`--pretty` — pretty-print JSON.
+
+`--confirm` — required for `apply` (mutates the database).
+
+Registry context is required. Use `--rails`, `--registry`, or pre-register tables in Ruby before invoking the CLI.
+
+When using `--registry` without `--rails`, set `DATABASE_URL` so the CLI can connect through `PartitionGardener::PgConnection`.
+
+## Examples
+
+Dry-run plan for one table:
+
+```bash
+cd /path/to/rails/app
+bundle exec partition_gardener --rails plan user_workdays --pretty
+```
+
+Audit every table in a JSON registry:
+
+```bash
+bundle exec partition_gardener --registry config/partition_garden.json audit --all --pretty
+```
+
+Apply maintenance to one table:
+
+```bash
+bundle exec partition_gardener --rails apply --confirm audits
+```
+
+Apply all registered gardener-owned tables:
+
+```bash
+bundle exec partition_gardener --rails apply --all
+```
+
+Omitting a table name without `--all` also runs the full registry.
+
+## Related
+
+- [configuration.md](configuration.md) — registry format and global config
+- [background_job.md](background_job.md) — when to use a job instead of CLI apply
+- [audit_reference.md](audit_reference.md) — audit and plan output reference
+- [operations.md](operations.md) — when to plan vs apply

data/docs/configuration.md

@@ -0,0 +1,261 @@
+# Configuration
+
+Partition Gardener has two configuration layers:
+
+1. Global — `PartitionGardener.configure` in a Rails initializer (or before CLI use)
+2. Per-table — entries in `PartitionGardener::Registry` built from `Templates.*` or JSON
+
+Pick layout and maintainer first ([decision_flow.md](decision_flow.md), [tooling_split.md](tooling_split.md)). Use this document as the option reference.
+
+## Global configuration
+
+```ruby
+# config/initializers/partition_gardener.rb
+PartitionGardener.configure do |config|
+  config.notifier = ->(message_or_error, context: {}) {
+    Rails.logger.info(message_or_error)
+  }
+  config.statement_timeout_wrapper = ->(timeout, &block) {
+    DatabaseTimeout.statement_timeout(timeout, &block) # host-app helper
+  }
+  config.today_resolver = -> { Time.zone.today }
+  config.continue_on_error = true
+  config.advisory_lock_mode = :transaction
+  config.run_record_store = PartitionGardener::SqlRunRecordStore.new
+end
+```
+
+When the gem loads inside Rails, the railtie sets `connection_resolver` and `today_resolver` automatically.
+
+`notifier` (default: no-op proc) — receives errors and info messages with a `context:` hash (`table_name`, `job`, `action`, …).
+
+`connection_resolver` (default: `ActiveRecord::Base.connection` when Rails is loaded, else `PartitionGardener::PgConnection` from `DATABASE_URL`) — database connection for maintenance SQL.
+
+`statement_timeout_wrapper` (default: passthrough) — wraps each table's maintenance in a host timeout (recommended in production).
+
+`today_resolver` (default: `Date.today`) — reference date for archive, current, and future window math.
+
+`schema_name` (default: `"public"`) — schema searched for parent and child partitions.
+
+`continue_on_error` (default: `true`) — when one table fails, continue others; raise `RunFailed` at end with all errors.
+
+`advisory_lock_mode` (default: `:transaction` with Active Record, `:session` with standalone `PgConnection`) — `:transaction` uses `pg_try_advisory_xact_lock`; `:session` uses `pg_try_advisory_lock`.
+
+`analyze_after_rebalance` (default: `false`) — run `ANALYZE` on parent after tail rebalance (global default).
+
+`incremental_rebalance` (default: `true`) — skip unchanged tail partitions when resuming (global default).
+
+`run_record_enabled` (default: `true`) — persist phase checkpoints for resume (global default).
+
+`run_record_store` (default: `SqlRunRecordStore` when a database connection is available, else in-memory) — where rebalance checkpoints are stored.
+
+`strict_maintenance_backend_validation` (default: `false`) — when `true`, raise `MaintenanceBackend::ValidationError` on register if `maintenance_backend` disagrees with `partman.parent_config`; when `false`, notify only.
+
+`retention_detach_concurrently` (default: `false`) — detach dropped archive partitions with `CONCURRENTLY` (global default).
+
+### Advisory locks
+
+Each table run acquires `pg_advisory_lock(hashtext('partition_gardener'), hashtext(table_name))` (or the transaction-scoped variant).
+
+`:transaction` (default with Active Record) — lock is held for one table maintenance transaction. If another worker already holds it, the table is skipped (`lock_not_acquired` in run metrics) and maintenance continues for other tables. Prefer `:session` when a single table run can take many minutes, because `:transaction` keeps one database transaction open for the whole run.
+
+`:session` — lock spans the whole table run across multiple transactions; released in an `ensure` block. Default when the connection resolver returns `PgConnection`.
+
+Do not run two full `run!` jobs against the same table concurrently. Host apps should also limit concurrent maintenance jobs (see [background_job.md](background_job.md)).
+
+### Run records
+
+When a database connection is configured (Active Record or `DATABASE_URL`), `SqlRunRecordStore` creates `partition_gardener_run_records` on first use. Run records let incremental rebalance resume after partial failure. Disable with `config.run_record_enabled = false` or per-table `run_record_enabled: false`.
+
+## Per-table registration
+
+Register one config hash per partitioned parent (composite layouts expand to child configs internally).
+
+```ruby
+PartitionGardener::Registry.register_template(
+  :sliding_window_monthly,
+  table_name: "audits",
+  partition_key_column: "created_at::date",
+  conflict_key: %w[id created_at],
+  active_months: 12,
+  move_batch_size: 10_000,
+  statement_timeout: 10.minutes,
+  retention_months: 24
+)
+
+# equivalent two-step form:
+# Registry.register(Templates.sliding_window_monthly(...))
+
+# or bulk:
+PartitionGardener::Registry.register_all([config_a, config_b])
+```
+
+`Registry.register_template` calls the matching `Templates` builder, then `Registry.register`. `Registry.register` normalizes the config, validates `maintenance_backend` against `partman.part_config`, and replaces any prior entry with the same `table_name`.
+
+### Template builders
+
+`Templates.sliding_window_monthly` — layout `:sliding_window`, bucket `:month`; key option `active_months` (default 12).
+
+`Templates.sliding_window_daily` — bucket `:day`; key option `active_days` (default 90).
+
+`Templates.sliding_window_weekly` — bucket `:week`; key option `active_weeks` (default 52).
+
+`Templates.sliding_window_quarterly` — bucket `:quarter`; key option `active_quarters` (default 8).
+
+`Templates.rolling_current_monthly` — layout `:rolling_current`; monthly sliding window without heat splits.
+
+`Templates.calendar_year` — layout `:calendar_year`; key option `active_years` (default 2).
+
+`Templates.premake_monthly` — layout `:premake_monthly`; key option `premake_months` (default 3).
+
+`Templates.integer_window` — layout `:integer_window`; key options `active_id_lo`, `active_id_width`, `current_band_size`, `archive_band_size`.
+
+`Templates.hash_branches` — layout `:hash_branches`; key option `hash_modulus`.
+
+`Templates.list_split` — layout `:list_split`; key option `branches`. Each branch needs `name` and `value`. Provide a structured `predicate` (`column`, `operator`, `value`), or omit it when `partition_key_column` (or `discriminator_column` on composite parents) matches the equality column and `value` is the partition key.
+
+Supported predicate operators: `eq`, `ne`, `is_null`, `is_not_null`. Column names must be simple identifiers; values are quoted through the database connection.
+
+```ruby
+Templates.list_split(
+  table_name: "repository_packages",
+  partition_key_column: "branch",
+  conflict_key: %w[id],
+  branches: [
+    {name: "cached", value: "cached"},
+    {
+      name: "workspace",
+      value: "workspace",
+      predicate: {column: "branch", operator: "eq", value: "workspace"}
+    }
+  ]
+)
+```
+
+Legacy `where_condition` SQL fragments are still accepted but should be migrated to predicates.
+
+`Templates.composite_list_hash` — layout `:composite`, `parent_mode: :list`; LIST parent plus HASH branches.
+
+`Templates.composite_list_range` / `Templates.list_range` — LIST parent plus RANGE sliding-window branches.
+
+`Templates.composite_range_hash` — RANGE parent plus HASH child tables.
+
+`Templates.composite_range_list` — RANGE parent plus LIST child tables.
+
+See [partition_landscape.md](partition_landscape.md) for the template catalog and out-of-scope patterns.
+
+All templates accept shared options passed through to the registry hash:
+
+`partition_key_column` (required) — column or SQL expression used for routing and moves.
+
+`conflict_key` (required) — unique key columns for idempotent batch moves (must match a parent unique index). Include the partition key so the index is valid on partitioned parents and maintenance can target one child; see [partition_landscape.md](partition_landscape.md).
+
+`move_batch_size` (default: `10_000`, constant `MOVE_BATCH_SIZE`) — rows per move batch.
+
+`split_row_threshold` (default: `100_000`) — heat split threshold inside the active window.
+
+`statement_timeout` (default: `300` seconds global default) — per-table override for `run!`.
+
+`retention_months` (default: none) — drop or detach archive partitions older than N months.
+
+`retention_apply` (default: `false`) — when `true`, detach or drop expired archive children; when `false`, notifier logs would-drop partitions only. See [retention.md](retention.md).
+
+`retention_keep_table` (default: `false`) — detach but do not drop expired partitions.
+
+`retention_detach_concurrently` (default: global default) — per-table override for concurrent detach.
+
+`maintenance_backend` (default: `:gardener`) — `:gardener`, `:pg_partman`, or `:hybrid_layout_only`.
+
+`incremental_rebalance` (default: global default) — per-table override.
+
+`run_record_enabled` (default: global default) — per-table override.
+
+`analyze_after_rebalance` (default: global default) — per-table override.
+
+Advanced Ruby-only keys (not in JSON import): `partition_name_format`, `partition_definition`, `extract_partition_identifier` procs. Prefer templates so these defaults stay consistent.
+
+### Maintenance backend
+
+`:gardener` (default) — gardener runs premake, tail rebalance, default drain, and retention; partman runs nothing.
+
+`:pg_partman` — gardener does nothing (table skipped in `run!`); partman runs premake and retention.
+
+`:hybrid_layout_only` — gardener runs tail rebalance, default drain, and gap repair only; partman runs premake and simple retention.
+
+On register, Gardener warns when partman and gardener both claim the same parent. Set `strict_maintenance_backend_validation: true` in `PartitionGardener.configure` to raise `MaintenanceBackend::ValidationError` instead of notifying. See [tooling_split.md](tooling_split.md).
+
+## JSON registry files
+
+Portable table fields are defined in [schemas/partition_garden.schema.json](schemas/partition_garden.schema.json). The schema `$id` is the raw GitHub URL (`https://raw.githubusercontent.com/amkisko/partition_gardener.rb/main/docs/schemas/partition_garden.schema.json`); pin a release tag instead of `main` when you need a fixed version for editor validation. The gem validates against the bundled copy under `docs/schemas/`, not by fetching that URL.
+
+`statement_timeout` is stored in seconds in JSON. Ruby registration accepts integer seconds; when Active Support is loaded, duration helpers such as `10.minutes` are also accepted.
+
+```json
+{
+  "tables": [
+    {
+      "table_name": "audits",
+      "layout": "sliding_window",
+      "partition_key_column": "created_at::date",
+      "conflict_key": ["id", "created_at"],
+      "active_months": 12,
+      "move_batch_size": 10000,
+      "statement_timeout": 600,
+      "retention_months": 24,
+      "maintenance_backend": "gardener"
+    }
+  ]
+}
+```
+
+Load from Ruby:
+
+```ruby
+PartitionGardener::ConfigDocument.load_registry_file!("config/partition_garden.json")
+```
+
+Load from CLI:
+
+```bash
+bundle exec partition_gardener --registry config/partition_garden.json audit --all
+```
+
+Export from registered Ruby configs:
+
+```ruby
+PartitionGardener::ConfigDocument.export(config_hash)
+PartitionGardener::ConfigDocument.export_all(PartitionGardener::Registry.tables)
+```
+
+JSON import supports layouts: `sliding_window` (with optional `bucket`: day, week, month, quarter), `rolling_current`, `calendar_year`, `premake_monthly`, `integer_window`, `hash_branches`. Composite and `list_split` layouts must be registered in Ruby today.
+
+`load_registry_file!` validates each entry against [schemas/partition_garden.schema.json](schemas/partition_garden.schema.json) (required keys, allowed keys, importable layouts) before registration.
+
+### Registry trust boundary
+
+Registry entries are operator-controlled configuration, not end-user input.
+
+`partition_key_column` is embedded in generated SQL as a trusted expression. List-branch filters should use structured `predicate` hashes (rendered with quoted identifiers and values at registration). Legacy `where_condition` strings are still accepted but bypass that validation. Keep registry files and Ruby registration limited to trusted operators. Do not load registry JSON from untrusted upload paths without a separate review step.
+
+## Programmatic API
+
+`PartitionGardener.run!(table_name: "audits")` — run maintenance for one table.
+
+`PartitionGardener.run!(job_class_name: "PartitionMaintenanceJob")` — run all registered gardener-owned tables.
+
+`PartitionGardener.run!(dry_run: true)` — build plan reports without applying.
+
+`PartitionGardener.plan(table_name: "audits")` — plan report for one table.
+
+`PartitionGardener.audit("audits")` — read-only layout audit (default rows, gaps, horizon).
+
+`run!` skips tables that are not partitioned, use `maintenance_backend: :pg_partman`, or fail to acquire the advisory lock. Returns `RunSummary`; raises `RunFailed` when `continue_on_error` is false or after aggregating errors at the end.
+
+## Related
+
+- [background_job.md](background_job.md) — schedule `run!` from a host job
+- [cli.md](cli.md) — plan, audit, apply from the shell
+- [decision_flow.md](decision_flow.md) — when and how to partition
+- [operations.md](operations.md) — runbook and RunSummary
+- [audit_reference.md](audit_reference.md) — audit and plan fields
+- [retention.md](retention.md) — retention options in production

data/docs/cutover.md

@@ -0,0 +1,180 @@
+# Cutover and migration playbook
+
+Move a live non-partitioned table to declarative partitioning with minimal downtime. Creation DDL uses pg_party or SQL ([pg_party_recipe.md](pg_party_recipe.md)); runtime layout uses Partition Gardener after switch.
+
+## Prerequisites
+
+- Composite unique index including the partition key, matching `conflict_key` ([partition_landscape.md](partition_landscape.md)).
+- Registry entry chosen (typically `sliding_window_monthly`; see [decision_flow.md](decision_flow.md)).
+- Maintenance job scheduled or CLI access for the first `run!` after cutover.
+- Staging environment with production-shaped data and the same registry.
+
+## Phase 1: Creation (no traffic switch)
+
+1. Create shadow parent `p_events` (or your naming convention) with `PARTITION BY RANGE` on the partition key.
+2. Create `p_events_default` and minimal premake (current month and next month).
+3. Add indexes on the parent (unique on `conflict_key` columns).
+4. Do not rename production `events` yet.
+
+See [pg_party_recipe.md](pg_party_recipe.md) for a minimal migration outline.
+
+## Phase 2: Backfill
+
+1. Copy historical rows into `p_events` in batches keyed by partition window (month or bucket).
+2. Throttle batch size to protect production I/O; use the same `conflict_key` for idempotent upserts.
+3. Compare counts per month between source and shadow (`compare_table_counts` in hot-switch concern).
+4. Run application read-only queries against shadow in staging to validate pruning and scopes.
+
+Backfill window for hot-switch delta sync defaults to roughly three months before and after `today` at switch time; extend backfill if older rows must exist before switch.
+
+For cross-database copies (production → staging, or a second cluster during migration), [pgsync](https://github.com/ankane/pgsync) can move filtered subsets with `where` clauses and `--in-batches` on append-only history. Gardener does not run pgsync; schedule it outside `run!` windows so loads do not fight nightly layout work.
+
+## Phase 3: Hot switch
+
+Use `PartitionGardener::Migration::HotSwitchConcern` in a migration:
+
+```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],
+    swap_lock_timeout: "5s", # optional; nil disables; default is 5s when omitted
+    partition_config: PartitionGardener::Registry.hot_switch_partition_config("events")
+  }.freeze
+
+  def up
+    add_write_block_trigger("events") # optional: quiesce writes during final sync
+    wait_for_active_transactions("events")
+    sync_delta_data
+    analyze_shadow_partitions!
+    ensure_future_partitions_exist(months_ahead: 1)
+    hot_switch_tables
+    sync_delta_data(swapped: true) # optional: catch rows on events_old if write-block was skipped
+  end
+end
+```
+
+Switch sequence (inside `hot_switch_tables`):
+
+1. `SET LOCAL lock_timeout` when `swap_lock_timeout` is set (default `5s`).
+2. Rename live `events` → `events_old`.
+3. Rename `p_events` → `events`.
+4. Rename child partitions to match new parent prefix.
+5. Repoint serial/identity sequences to the live table (`ALTER SEQUENCE ... OWNED BY`).
+6. Remove write-block trigger from `events_old`.
+
+`months_ahead: 1` at switch is enough; gardener extends the sliding window nightly.
+
+`analyze_shadow_partitions!` runs `ANALYZE` on each shadow child and parent before swap. `sync_delta_data` accepts `source_table`, `target_table`, `swapped: true` (post-swap catch-up from `events_old`), `sleep_seconds` between batches, and `batch_size`.
+
+## Cutover comparison: pgslice
+
+[pgslice](https://github.com/ankane/pgslice) solves the same cutover problem with a CLI: `prep` → `add_partitions` → `fill` → `analyze` → `swap`, then optional `fill --swapped` for rows that landed on the retired table after the first fill. Gardener's `HotSwitchConcern` covers the swap phase in a Rails migration, plus live-delta sync and optional write quiesce.
+
+### Step comparison
+
+Shadow parent — pgslice uses `visits_intermediate` (`LIKE` + `PARTITION BY RANGE`); Gardener uses `p_events` (pg_party or SQL creation).
+
+Premake children — pgslice `add_partitions --intermediate`; Gardener `ensure_future_partitions_exist`.
+
+Copy rows — pgslice `fill` in id batches within partition bounds; Gardener Phase 2 backfill plus `sync_delta_data` (UPSERT, partition-key window).
+
+Statistics — pgslice `analyze` on each child and parent; Gardener `analyze_shadow_partitions!` before swap and `analyze_after_rebalance` on first `run!`.
+
+Atomic rename — pgslice renames `visits` → `visits_retired`, intermediate → `visits`; Gardener renames `events` → `events_old`, `p_events` → `events`, and children.
+
+Catch-up after rename — pgslice `fill --swapped` from retired to live; Gardener `sync_delta_data(swapped: true)` or write-block trigger before swap.
+
+Rollback drill — pgslice `unswap`; Gardener `hot_unswitch_tables`.
+
+The rename swap uses the same low-downtime pattern: metadata (table name) flips in one transaction; the app keeps querying `events` without code changes.
+
+### Gardener extras for live cutover
+
+Delta sync before switch — `sync_delta_data` upserts only rows in a sliding date window that are missing or stale on the shadow table (`updated_at` comparison). pgslice's first `fill` is id-batch oriented and assumes a numeric primary key; catch-up after rename is a separate `fill --swapped` pass.
+
+Write quiesce — optional `add_write_block_trigger` plus `wait_for_active_transactions` narrow the race between last sync and rename.
+
+Registry handoff — after swap, `Registry` plus nightly `run!` own runtime maintenance. pgslice stops at swap and expects a cron `add_partitions` you must later disable ([tooling_split.md](tooling_split.md)).
+
+### Hot-switch config reference
+
+`swap_lock_timeout` — default `"5s"`. Sets `SET LOCAL lock_timeout` in swap/unswitch transaction; `nil` disables.
+
+`sync_batch_size` — default `PartitionGardener::MOVE_BATCH_SIZE`. Rows per `sync_delta_data` batch.
+
+`sync_stale_column` — default `"updated_at"`. Stale-row detection for upserts.
+
+Sequence repointing uses `pg_get_serial_sequence` per column; custom sequence names are supported.
+
+### Using pgslice for creation, Gardener for switch
+
+Valid hybrid when you do not use pg_party:
+
+1. `pgslice prep` / `add_partitions` / `fill` / `analyze` on the shadow tree.
+2. Register the table in Gardener before switch.
+3. Replace `pgslice swap` with a migration that calls `analyze_shadow_partitions!`, `sync_delta_data`, `ensure_future_partitions_exist`, and `hot_switch_tables`.
+4. Disable pgslice `add_partitions` cron; run Gardener nightly.
+
+Do not run pgslice premake and Gardener `run!` on the same parent without `maintenance_backend` coordination.
+
+## Phase 4: After cutover
+
+1. Register `events` in `PartitionGardener::Registry` if not already loaded.
+2. `bundle exec partition_gardener --rails audit events` — target default row count trending to zero.
+3. `bundle exec partition_gardener --rails plan events` — review first layout diff.
+4. `bundle exec partition_gardener --rails apply --confirm events` or wait for nightly job.
+5. Recompute bucket snapshots for dashboard totals if you use rollup tables ([partition_landscape.md](partition_landscape.md#aggregates-totals-and-snapshots)).
+6. Drop `events_old` only after retention policy, legal review, and verified row counts.
+
+## Rollback
+
+Before dropping `events_old`:
+
+1. Stop maintenance job for `events` or set maintenance window.
+2. Call `hot_unswitch_tables` in a migration, or reverse renames manually: `events` → `p_events`, `events_old` → `events`.
+3. Re-point application if any code assumed partitioned shape.
+4. Document registry removal to avoid gardener acting on the wrong parent.
+
+Rollback after `events_old` is dropped requires restore from backup; treat drop as irreversible.
+
+## Template upgrades
+
+### premake_monthly → sliding_window_monthly
+
+1. Register new template; `plan` to preview tail and default drain.
+2. Run `apply` during low traffic; expect `rows_moved` from default and tail reshape.
+3. Remove legacy cron premake jobs.
+
+### Changing bucket (monthly → weekly)
+
+Treat as a new partitioning scheme: new parent or full reload into a new tree. Gardener does not rewrite archive naming in place. Plan a new shadow table, backfill, and hot switch.
+
+### Composite trees
+
+Native PostgreSQL sub-partition DDL is your migration responsibility. Register each gardener-maintained node separately ([partition_landscape.md](partition_landscape.md#composite-trees)). Creation migration attaches the full tree; gardener plans each registered parent.
+
+## Cutover checklist
+
+- [ ] `conflict_key` matches parent unique index
+- [ ] Shadow backfill complete; counts match per bucket
+- [ ] `ensure_future_partitions_exist(months_ahead: 1)` succeeds
+- [ ] Hot switch migration applied
+- [ ] Sequences owned by live table, not `events_old` (`hot_switch_tables` repoints serial columns; verify after switch)
+- [ ] Registry loaded in all app processes
+- [ ] First `audit`: default rows acceptable or draining
+- [ ] First `apply` or nightly job succeeded
+- [ ] Application scopes and UI use partition key on hot paths
+- [ ] Snapshot rollups invalidated or recomputed for affected buckets
+- [ ] `events_old` drop scheduled with backup verification
+
+## Related
+
+- [pg_party_recipe.md](pg_party_recipe.md) — creation DDL sketch
+- [operations.md](operations.md) — post-cutover incidents
+- [host_testing.md](host_testing.md) — CI and staging for host apps
+- [tooling_split.md](tooling_split.md) — do not double-maintain with partman