partition_gardener 0.3.5 → 0.3.7

data/docs/issues/20260916113300_opaque-composite-public-ids.md

@@ -0,0 +1,55 @@
+# Opaque composite public identifiers
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+Treat database uniqueness, public identifier, routing hint, and authorization as four separate contracts. PostgreSQL uniqueness on a partitioned parent is composite because the partition key must sit in every unique index. That does not by itself decide what a person sees in a URL or API.
+
+When a single sequence or UUIDv7 keeps id unique across children, keep that logical id as the application identifier. Use self.primary_key = :id so to_param and JSON do not become Rails underscore composites such as 42_100. Still attach a routing hint on point lookups so SELECT can prune. Do not invent that hint from current month.
+
+When id is unique only inside a child, the public identifier for point lookups must carry every uniqueness column. Prefer one opaque path segment over Rails extract_value underscore form or a separate query parameter the caller can edit independently.
+
+If that segment is encoded, use unpadded base64url from RFC 4648 section 5, not standard base64. Standard base64 uses plus, slash, and padding equals, which are not URL-safe in a path. Encoding is packaging. Anyone can decode and re-encode another date or tenant. Tamper resistance needs an HMAC over a versioned payload, or a server-side mapping table. Encoding is not authorization. Lookups still go through an ownership set.
+
+After decode, query with both columns and fail closed. Do not fall back to id-only scan. A bad or unsigned token is 404, not a bounded retry across children.
+
+Do not hide browse context. List screens still show period, account, or branch in product language. Tenant and list keys for hot paths come from session or parent context, not from a tunable URL field. Point-lookup tokens may be opaque. Pagination cursors already belong in the same family as opaque tokens.
+
+Do not ship an encoder in this gem until a second in-repo caller needs it. Host applications own secrets, token version, and decode. Gardener docs should name the contract.
+
+Rails already covers the packaging the first pass sketched. Prefer those APIs over a homemade base64 string.
+
+signed_id (Rails 7+) is an HMAC token over record.id, SHA256, JSON, url_safe: true. The docs say the payload is encoded not encrypted. find_signed fails closed on a bad signature. That is the closest out-of-box match to one opaque URL-safe path segment. It only carries both uniqueness columns when primary_key is the composite array. Scalar self.primary_key = :id plus query_constraints still signs and finds by id alone, so SELECT can scan every child. query_constraints never feeds SELECT.
+
+to_param plus params.extract_value is the Rails CPK URL form. Default delimiter is underscore (4_2). Callers can edit either half. Dates and other values that contain underscore split wrong unless param_delimiter is changed. Use this for private admin paths, not for a public identifier that must not be tunable.
+
+generates_token_for can embed extra JSON (password salt, or occurred_on) and re-check it after fetch. Lookup still yields only the primary key into find_by or find. Extra JSON is not a WHERE predicate and is plaintext in the token. CPK find_by_token_for was fixed in 2024 (Rails 7.2/8.0). find_signed CPK wrap landed later (Rails 8.1 / 2026-04). Gardener's development floor is ActiveRecord 7.1, so hosts on 7.1 cannot treat signed CPK find as solved.
+
+has_secure_token stores a random Base58 string (URL-safe by alphabet). It is a mapping column, not an encoding of composite values. PostgreSQL still forbids a unique index on token alone on a partitioned parent unless the partition key is in that index. Lookup by token without the partition key then cannot prune, or the unique index cannot exist. Put the mapping on an unpartitioned table, or keep a globally unique logical id on the fact row.
+
+GlobalID locates with Model.find(model_id). Composite keys become gid://app/Event/123/2026-03-15 (slash, CGI.escape, max 20 segments). Unsigned. to_param is unpadded base64url of that URI, still decodable. SignedGlobalID HMAC-wraps the same URI. Locator find prunes only when primary_key is the composite.
+
+ActiveSupport::MessageVerifier is the primitive under signed_id, token_for, and SignedGlobalID. Default MessageVerifier is not URL-safe (plus, slash, padding). signed_id and GlobalID::Verifier opt into url_safe. MessageEncryptor exists; do not encrypt identifiers. CurrentAttributes can hold session tenant for list filters; that is not a public id.
+
+## Effects
+
+Added Public identifiers to docs/application_contract.md. Pointers from docs/partition_landscape.md Rails application contract, routing hints, and UI surfaces. README application_contract blurb names public identifiers. CHANGELOG Unreleased and usr/docs/changelogs/20260916144600_public-identifiers-contract.md record the doc contract.
+
+## Next
+
+Host docs only. No encoder in the gem. No RFC unless a later change makes public identifiers a user-facing gem contract.
+
+## Source
+
+Triggered by a review question: should composite ids for users be a single base64 string of composite values so callers cannot easily tune them and so the value stays URL-safe.
+
+Later pass accepted the proposal as host documentation. Vendor product names stay out of the host contract; they remain a Source citation only.
+
+Existing repo text: docs/partition_landscape.md Opaque tokens may encode (id, partition_key); Rails query_constraints; UI and product surfaces require visible period or tenant for browse. docs/application_contract.md query_constraints when logical id is not globally unique.
+
+Materialized in docs/application_contract.md Public identifiers, docs/partition_landscape.md pointers, README application_contract blurb.
+
+External: GitLab Database table partitioning, Rails Composite Primary Keys guide to_param 4_2 and extract_value, ActiveRecord::SignedId (url_safe MessageVerifier, find_by primary_key => [id] on main), ActiveRecord::TokenFor payload_for [id, block.as_json], has_secure_token SecureRandom.base58, URI::GID COMPOSITE_MODEL_ID_DELIMITER slash, GlobalID to_param unpadded base64url, Rails PRs 52798 and 57245, RFC 4648 section 5 base64url, GraphQL Relay global object identification, OWASP Insecure Direct Object Reference Prevention Cheat Sheet.

data/docs/issues/20260917123253_ci-drop-automatic-dependency-audit.md

@@ -0,0 +1,28 @@
+CI quality failed on a trailing blank line in spec/support/junit_formatter.rb. Test CI also ran bundler-audit or osv-scanner, which fail whenever an advisory lands even when a separate dependency audit already exists.
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+- Drop bundler-audit and security jobs from test.yml so tests no longer wait on advisory freshness.
+- Keep dependency-audit.yml as workflow_dispatch only. Do not run it on push, pull request, or schedule.
+- Disable osv-scanner in Trunk Check.
+- Disable markdownlint MD013 in .markdownlint.yaml. Keep AGENTS.md in Trunk so other markdownlint rules still run.
+- Keep lockfile and spec fixes that were already blocking quality or tests.
+
+## Effects
+
+- Test CI runs lint and specs without an advisory gate.
+- Trunk Check no longer treats dependency CVEs as a required check.
+- Manual dependency-audit remains available on workflow_dispatch.
+
+## Next
+
+- Run dependency audit on demand when a release or a known advisory needs it.
+- Do not reintroduce advisory scanners into test.yml.
+
+## Source
+
+- GitHub Actions test and Trunk Check failures on 2026-09-17

data/docs/operations.md

@@ -83,7 +83,7 @@ table is not a partitioned table — registry typo or wrong connection. Action:
 
 ## Failed or partial runs
 
-Gardener persists checkpoints in `partition_gardener_run_records` when `run_record_enabled` is true (default).
+Gardener persists checkpoints in `partition_gardener_checkpoints` when `run_record_enabled` is true (default). Override the table with `run_record_table_name`.
 
 1. Read `errors` and notifier context (`table_name`, `action`).
 2. `audit TABLE` — confirm default count and gaps unchanged or worse.

data/docs/partition_landscape.md

@@ -2,7 +2,7 @@
 
 Partition Gardener targets PostgreSQL native declarative partitioning with gardener-owned maintenance plans. This page maps industry patterns to what the gem implements, documents experimental layouts, and lists what belongs outside the gem.
 
-Canonical home for routing (layers, recovery ladder, hints), pruning, UI scoping, and aggregate snapshots. Host query and write obligations live in [application_contract.md](application_contract.md). Cross-engine portability lives in [partition_engines.md](partition_engines.md).
+Canonical home for routing (layers, recovery ladder, hints), pruning, UI scoping, and aggregate snapshots. Host query, write, and public identifier obligations live in [application_contract.md](application_contract.md). Cross-engine portability lives in [partition_engines.md](partition_engines.md).
 
 ## Implemented templates
 
@@ -113,6 +113,8 @@ end
 
 `query_constraints` (Rails 7.1+) adds listed columns to `UPDATE` and `DELETE` `WHERE` clauses so writes can prune. It does not add the partition key to `SELECT` lookups: `Event.find(id)` may still scan all partitions unless `id` is globally unique and the planner can prove a single child.
 
+Public URLs and API ids are a separate contract from `query_constraints`. See [application_contract.md](application_contract.md#public-identifiers).
+
 For reads, encode the contract in scopes used by hot paths:
 
 ```ruby
@@ -150,7 +152,7 @@ Recovery ladder (prefer earlier steps):
 #### Exact key (preferred)
 
 - Denormalize the parent business date (or tenant/branch) onto the child at insert time; filter and join on the child column.
-- Store the partition key next to the logical id in API cursors, job args, outbox payloads, and admin deep links. Opaque tokens may encode `(id, partition_key)` so clients never send id-only.
+- Store the partition key next to the logical id in API cursors, job args, outbox payloads, and admin deep links. Opaque tokens may encode `(id, partition_key)` so clients never send id-only ([application_contract.md](application_contract.md#public-identifiers)).
 - Use a generated column when the key is a stable expression of an existing column the planner can see (`created_at::date` registered and filtered the same way).
 
 #### Orientation / range from a related record
@@ -218,7 +220,7 @@ Registry `conflict_key` must match a parent unique index and should include the
 
 ### UI and product surfaces
 
-Partition boundaries are an application contract, not only a database detail. Screens and APIs should make the same separation key visible to people so routine work stays inside one prune-friendly slice. User-facing copy should describe periods, accounts, or branches in product language, not partitions, shards, or child tables.
+Partition boundaries are an application contract, not only a database detail. Screens and APIs should make the same separation key visible to people so routine work stays inside one prune-friendly slice. User-facing copy should describe periods, accounts, or branches in product language, not partitions, shards, or child tables. Point-lookup URLs may use an opaque token; list and filter screens still show the period or tenant ([application_contract.md](application_contract.md#public-identifiers)).
 
 Time-partitioned data (monthly sliding window):
 
@@ -410,7 +412,7 @@ Operations and migration docs in this repository:
 
 - [operations.md](operations.md) — runbook
 - [cutover.md](cutover.md) — hot-switch playbook
-- [application_contract.md](application_contract.md) — host app behavior
+- [application_contract.md](application_contract.md) — host app behavior, public identifiers
 - [monitoring.md](monitoring.md) — metrics and alerts
 - [retention.md](retention.md) — archive detach and drop
 - [audit_reference.md](audit_reference.md) — audit and plan catalog

data/docs/reviews/20261021220000_engineering-audit-0-3-7.md

@@ -0,0 +1,30 @@
+# Engineering audit and 0.3.7 fixes
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+- Run a multi-model engineering audit on `partition_gardener` (correctness, tests, hot-path, contracts).
+- Fact-check findings in source before shipping.
+- Ship high-confidence correctness and contract fixes as patch `0.3.7`.
+- Defer structural refactors (PlanApplier phase machine collapse, HotSwitchConcern split, strategy mixin extraction, default statement_timeout wrapper) to later work.
+
+## Effects
+
+- Confirmed and fixed: resume skips detach while phase is `detach`; hot-switch child rename skip on `p_` prefix; serial sequence default left on `_old`; unbounded `sync_delta_data` when stale column missing; `CREATE IF NOT EXISTS … PARTITION OF` no-op on detached name; lexicographic integer gap sort; leap-day `add_years`; retention notify says drop when table kept; JSON registry omits integer window keys.
+- Unit specs: 151 examples, 0 failures (`bundle exec rspec` on non-integration paths from `spec/spec_paths.txt`).
+- Integration resume examples extended for row-count preservation and started-but-not-detached phase; not run in this session (needs `INTEGRATION=1` and Postgres).
+
+## Next
+
+- Run `INTEGRATION=1` resume and hot-switch specs before cutting the gem.
+- Run `ruby usr/bin/release.rb` when the working tree is clean and ready to push to RubyGems.
+- Follow-up: session advisory lock default for long copies; statement_timeout wrapper; RFC 0002 status; dead `SCHEMA_PATH` wiring or removal.
+
+## Source
+
+- Audit agents: correctness, tests/coverage, hot-path/resource, org/contracts.
+- Branch: `patch/engineering-audit-0-3-7`
+- Related changelog: `docs/changelogs/20261021220000_cut-patch-release-0-3-7.md`

data/docs/reviews/20261028075216_engineering-audit-release-preparation.md

@@ -0,0 +1,35 @@
+# Engineering audit and release preparation
+
+## Decisions
+
+- Continue on main while preserving the pre-existing uncommitted changes. Do not commit, tag, push, or publish.
+- Retain release version 0.3.7. Reconcile root and appraisal PATH metadata without updating third-party dependency versions.
+- Review correctness, executable coverage, workflow triggers and permissions, package boundaries, resource cost, and trace/identity boundaries. Re-audit the changed paths after corrections.
+
+## Effects
+
+- Correct the resume integration fixture's initial expectation: the source rows initially belong to the attached current partition, and the hot monthly partition exists after rebalance.
+- Restore the required lint gate by combining adjacent boundary stubs. Verify all integration examples against an isolated PostgreSQL server, including the existing rebalance and hot-switch changes.
+- Synchronize the own-gem PATH version in the root and appraisal lockfiles to 0.3.7, enable pull-request tests, and restrict workflow permissions to contents: read.
+- Fix the release confirmation guard in usr/bin/release.rb so EOF refuses publication. An explicit Enter still selects the displayed default. The process-boundary regression test executes the release script with command execution replaced at the operating-system boundary; no publication command runs against a real service. The shared regression was observed first in Favorites: 2 examples, 1 failure before correction and 2 examples, 0 failures after correction. The release specs pass in every repository.
+- Final serial JSON report: 188 examples, 0 failures with INTEGRATION=1 and PostgreSQL; no pending integration examples.
+- Required project checks passed: DATABASE_URL=postgres://postgres@127.0.0.1:55432/partition_gardener_test make test. Environment: Ruby 4.0.2, BUNDLE_PATH=vendor/bundle; the installed native extensions require that Ruby build.
+- Build the gem, verify it with Gem::Package#verify, and check that the changelog heading matches the gem version. Final package measurements are recorded in the session output; this gem includes the review note itself.
+- Cold process measurement on macOS arm64 with /usr/bin/time -l and bundle exec ruby -Ilib: 0.35 CPU seconds, 0.7 elapsed seconds, 31817728 peak RSS bytes. Favorites loads Rails before the engine. Local smoke ceilings: 1 MiB compressed gem, 128 MiB RSS, 2 CPU seconds. All measured values fit those ceilings. CPU seconds are the energy proxy; electricity use was not measured.
+- Parse every workflow YAML, verify lockfile own-gem versions, and run git diff --check. All passed. All six assigned repositories remain on main.
+
+## Next
+
+- No confirmed correction remains in the reviewed changes. Hosted GitHub Actions and the complete supported Ruby/framework matrix were not executed locally.
+- Scope limits: production traffic, production database size and query plans, external service retention, and co-located resource interference were not measured. The local byte/RSS/CPU results do not establish those properties.
+- Trace review follows local file/log and protocol emissions. No live customer identities or credentials were used. Data retention and deletion in embedding applications remain host contracts.
+- Learned-system training/evaluation and cloud deployment modes do not apply to these library trees. Native memory-boundary mode applies to Polyrun's extension; browser presentation applies to Favorites; HTTP/identity and message companions apply only to repositories that expose those boundaries. Libraries have no independent production health endpoint to assess.
+
+## Source
+
+- AGENTS.md
+- .agents/skills/engineering-audit/SKILL.md
+- .agents/skills/changelog-update/SKILL.md
+- CHANGELOG.md
+- Makefile
+- spec/README.md

data/docs/reviews/20261029150855_engineering-audit-release-preparation.md

@@ -0,0 +1,43 @@
+# Engineering audit and release preparation
+
+## Participants
+
+Andrei Makarov (@amkisko)
+
+## Decisions
+
+- Continue on main while preserving uncommitted work. Do not commit, tag, push, or publish.
+- Keep release version 0.3.7. Set the CHANGELOG heading date to 2026-10-29. RubyGems still lists 0.3.6 as the latest published version.
+- Re-check correctness, executable coverage, workflow triggers and permissions, package boundaries, resource cost, and database-boundary behavior after the prior release-prep pass.
+
+## Effects
+
+- Enable `pull_request` on the test workflow, keep token permissions at `contents: read`, and cancel superseded runs.
+- Set the `CHANGELOG.md` heading for 0.3.7 to 2026-10-29 and align the cut note under `docs/changelogs/`.
+- Final serial JSON report: 188 examples, 0 failures with `INTEGRATION=1` and PostgreSQL on port 5432; no pending examples. Parallel polyrun with five workers: exit 0.
+- Required project checks passed: rubocop (116 files, no offenses), rbs validate, `INTEGRATION=1` polyrun parallel-rspec. Environment: Ruby 4.0.2, `BUNDLE_PATH=vendor/bundle`.
+- `release_spec`: 2 examples, 0 failures (EOF refuses gem push; Enter accepts the displayed default with system execution replaced).
+- Build the gem, verify it with `Gem::Package#verify`, and confirm the changelog heading matches version 0.3.7. Compressed package: 117760 bytes; source payload: 495104 bytes across 104 packaged paths. These are compressed versus uncompressed sizes, not interchangeable quantities.
+- Cold process measurement on macOS arm64 with `/usr/bin/time -p` and `bundle exec ruby -Ilib`: 0.17 CPU seconds, 0.26 elapsed seconds. Peak RSS via `/usr/bin/time -l` was unavailable in this session (`sysctl kern.clockrate` refused). Prior release-prep peak RSS on the same require path was 31817728 bytes. Local smoke ceilings: 1 MiB compressed gem, 128 MiB RSS, 2 CPU seconds. Measured gem size and CPU fit those ceilings. CPU seconds are the energy proxy; electricity use was not measured.
+- Parse every workflow YAML, verify lockfile own-gem versions at 0.3.7, and run `git diff --check`. All passed.
+
+## Next
+
+- Commit, tag 0.3.7, push, and publish remain operator steps; this session did not run them. When the tree is clean, `make release` runs gem push, tag, and GitHub release.
+- Hosted GitHub Actions and the complete supported Ruby/framework matrix were not executed locally beyond the default Gemfile path used by `make test`.
+- Re-measure peak RSS with `/usr/bin/time -l` outside the restricted session if a fresh number is required before publish.
+- Scope limits: production traffic, production database size and query plans, external service retention, and co-located resource interference were not measured. The local byte/CPU results do not establish those properties.
+- Trace review follows local file/log and protocol emissions. No live customer identities or credentials were used. Data retention and deletion in embedding applications remain host contracts.
+- Learned-system training/evaluation and cloud deployment modes do not apply to this library tree. Database-boundary mode applies to PostgreSQL maintenance DDL and checkpoint resume. The library has no independent production health endpoint to assess.
+
+## Source
+
+- AGENTS.md
+- .agents/skills/engineering-audit/SKILL.md
+- .agents/skills/changelog-update/SKILL.md
+- CHANGELOG.md
+- Makefile
+- spec/README.md
+- docs/reviews/20261028075216_engineering-audit-release-preparation.md
+- docs/reviews/20261021220000_engineering-audit-0-3-7.md
+- docs/changelogs/20261021220000_cut-patch-release-0-3-7.md

data/docs/schemas/partition_garden.schema.json

@@ -60,6 +60,22 @@
       "minimum": 1,
       "maximum": 10
     },
+    "active_id_lo": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "active_id_width": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "current_band_size": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "archive_band_size": {
+      "type": "integer",
+      "minimum": 1
+    },
     "premake_months": {
       "type": "integer",
       "minimum": 0,

data/lib/partition_gardener/archive_retention.rb

@@ -35,15 +35,18 @@ module PartitionGardener
         next if bucket >= DateCalendar.beginning_of_month(cutoff)
 
         if apply_retention
+          keep_table = @config.fetch(:retention_keep_table, false)
           @executor.detach_partition(table_name, partition.name, concurrently: detach_concurrently?)
-          @executor.drop_table(partition.name) unless @config.fetch(:retention_keep_table, false)
+          @executor.drop_table(partition.name) unless keep_table
 
+          action = keep_table ? "Detached" : "Dropped"
           PartitionGardener.configuration.notify(
-            "[PartitionGardener] Dropped archive partition #{partition.name} (retention #{retention_months} months)",
+            "[PartitionGardener] #{action} archive partition #{partition.name} (retention #{retention_months} months)",
             context: {
               table_name: table_name,
               partition_name: partition.name,
               retention_months: retention_months,
+              retention_keep_table: keep_table,
               job: @job_class_name
             }
           )
@@ -51,8 +54,9 @@ module PartitionGardener
           next
         end
 
+        preview_action = @config.fetch(:retention_keep_table, false) ? "detach" : "drop"
         PartitionGardener.configuration.notify(
-          "[PartitionGardener] Would drop archive partition #{partition.name} (bucket #{bucket}, retention #{retention_months} months)",
+          "[PartitionGardener] Would #{preview_action} archive partition #{partition.name} (bucket #{bucket}, retention #{retention_months} months)",
           context: {
             table_name: table_name,
             partition_name: partition.name,

data/lib/partition_gardener/config_document.rb

@@ -14,6 +14,10 @@ module PartitionGardener
       active_weeks
       active_quarters
       active_years
+      active_id_lo
+      active_id_width
+      current_band_size
+      archive_band_size
       premake_months
       split_row_threshold
       move_batch_size

data/lib/partition_gardener/configuration.rb

@@ -15,7 +15,7 @@ module PartitionGardener
       :strict_maintenance_backend_validation,
       :current_run_metrics
 
-    attr_writer :run_record_store
+    attr_writer :run_record_store, :run_record_table_name
 
     def initialize
       @notifier = ->(_message_or_error, context: {}) {}
@@ -28,6 +28,7 @@ module PartitionGardener
       @analyze_after_rebalance = false
       @incremental_rebalance = true
       @run_record_enabled = true
+      @run_record_table_name = SqlRunRecordStore::TABLE_NAME
       @run_record_store = nil
       @retention_detach_concurrently = false
       @align_child_columns = true
@@ -39,6 +40,13 @@ module PartitionGardener
       @run_record_store ||= default_run_record_store
     end
 
+    def run_record_table_name
+      name = @run_record_table_name.to_s.strip
+      raise ArgumentError, "run_record_table_name is blank" if name.empty?
+
+      name
+    end
+
     def connection
       resolved = @connection_resolver.call
       raise ArgumentError, "PartitionGardener connection is not configured" unless resolved

data/lib/partition_gardener/date_calendar.rb

@@ -52,14 +52,11 @@ module PartitionGardener
     end
 
     def add_years(date, count)
-      value = to_date(date)
-      Date.new(value.year + count, value.month, value.day)
+      to_date(date) >> (count * 12)
     end
 
     def add_months(date, count)
-      base = beginning_of_month(date)
-      month_index = (base.year * 12) + (base.month - 1) + count
-      Date.new(month_index / 12, (month_index % 12) + 1, 1)
+      beginning_of_month(date) >> count
     end
   end
 end

data/lib/partition_gardener/gap_detection.rb

@@ -20,7 +20,7 @@ module PartitionGardener
       segments = strategy.attached_tail_segments
       return [] if segments.empty?
 
-      sorted = segments.sort_by { |segment| [segment.range_start.to_s, segment.name] }
+      sorted = segments.sort_by { |segment| [segment.range_start, segment.name] }
       gaps = []
 
       sorted.each_cons(2) do |left, right|

data/lib/partition_gardener/migration/hot_switch_concern.rb

@@ -175,11 +175,13 @@ module PartitionGardener
         conflict_match = conflict_key.map { |column| "d.#{connection.quote_column_name(column)} = s.#{connection.quote_column_name(column)}" }.join(" AND ")
         update_columns = insert_columns - conflict_key
         update_clause = update_columns.map { |column| "#{connection.quote_column_name(column)} = EXCLUDED.#{connection.quote_column_name(column)}" }.join(", ")
-        stale_check = if partitioned_columns.include?(stale_column)
-          "d.#{connection.quote_column_name(stale_column)} >= s.#{connection.quote_column_name(stale_column)}"
-        else
-          "FALSE"
+        unless current_columns.include?(stale_column) && partitioned_columns.include?(stale_column)
+          raise ArgumentError,
+            "sync_stale_column #{stale_column.inspect} is missing from source or target; " \
+            "refusing unbounded delta sync"
         end
+
+        stale_check = "d.#{connection.quote_column_name(stale_column)} >= s.#{connection.quote_column_name(stale_column)}"
         window_predicate = [
           "#{current_partition_key_expression} >= #{start_date_sql}",
           "AND #{current_partition_key_expression} < #{end_date_sql}",
@@ -209,16 +211,11 @@ module PartitionGardener
           <<~SQL.chomp
             ON CONFLICT (#{conflict_key_str}) DO NOTHING
           SQL
-        elsif partitioned_columns.include?(stale_column)
-          <<~SQL.chomp
-            ON CONFLICT (#{conflict_key_str}) DO UPDATE SET
-              #{update_clause}
-            WHERE #{quoted_table(target_table)}.#{connection.quote_column_name(stale_column)} < EXCLUDED.#{connection.quote_column_name(stale_column)}
-          SQL
         else
           <<~SQL.chomp
             ON CONFLICT (#{conflict_key_str}) DO UPDATE SET
               #{update_clause}
+            WHERE #{quoted_table(target_table)}.#{connection.quote_column_name(stale_column)} < EXCLUDED.#{connection.quote_column_name(stale_column)}
           SQL
         end
 
@@ -406,17 +403,29 @@ module PartitionGardener
       def rename_partition_children!(parent_table, from_prefix, to_prefix)
         fetch_partitions(parent_table).each do |partition|
           partition_name = partition.to_s
-          next if partition_name.include?(to_prefix)
+          bare_name = partition_name.delete('"').split(".").last
+          next unless bare_name.include?(from_prefix)
 
-          new_partition_name = partition_name.gsub(from_prefix, to_prefix)
-          run_sql "ALTER TABLE #{partition} RENAME TO #{new_partition_name}"
-          say "Renamed #{partition} to #{new_partition_name}"
+          new_bare_name = bare_name.sub(from_prefix, to_prefix)
+          next if new_bare_name == bare_name
+
+          run_sql "ALTER TABLE #{partition} RENAME TO #{connection.quote_column_name(new_bare_name)}"
+          say "Renamed #{partition} to #{new_bare_name}"
         end
       end
 
       def repoint_serial_sequences!(table_name, sequence_pairs)
         sequence_pairs.each do |column_name, sequence_name|
-          run_sql "ALTER SEQUENCE #{sequence_name} OWNED BY #{quoted_table(table_name)}.#{connection.quote_column_name(column_name)}"
+          quoted_column = connection.quote_column_name(column_name)
+          live_table = quoted_table(table_name)
+          run_sql <<~SQL
+            ALTER TABLE #{live_table}
+            ALTER COLUMN #{quoted_column}
+            SET DEFAULT nextval(#{connection.quote(sequence_name)}::regclass)
+          SQL
+          run_sql "ALTER SEQUENCE #{sequence_name} OWNED BY #{live_table}.#{quoted_column}"
+          max_id = run_sql("SELECT COALESCE(MAX(#{quoted_column}), 1) AS max_id FROM #{live_table}").first["max_id"].to_i
+          run_sql "SELECT setval(#{connection.quote(sequence_name)}, #{[max_id, 1].max})"
           say "Repointed #{sequence_name} to #{table_name}.#{column_name}"
         end
       end

data/lib/partition_gardener/plan_applier.rb

@@ -139,8 +139,10 @@ module PartitionGardener
     end
 
     def apply_resuming!(plan, operations, staging_name, record)
-      unless record.phase_at_least?("detach")
-        prepare_staging!(staging_name)
+      # RunRecord.start persists phase "detach" before work. Treat detach as done only once
+      # the record has advanced to "segments" or later.
+      unless record.phase_at_least?("segments")
+        prepare_staging!(staging_name) unless Connection.partition_exists?(staging_name)
         detach_managed_tail_partitions!(staging_name, skip_names: keep_names_from(operations))
         drain_default_tail_rows_into_staging!(staging_name)
         record = record.advance!("detach", staging_row_count: staging_row_count(staging_name))
@@ -185,11 +187,21 @@ module PartitionGardener
       segments.each do |segment|
         next if Connection.partition_attached?(table_name, segment.name)
 
+        if Connection.partition_exists?(segment.name)
+          raise StandardError,
+            "partition #{segment.name} exists but is not attached to #{table_name}; " \
+            "CREATE TABLE IF NOT EXISTS … PARTITION OF would no-op and leave rows stranded"
+        end
+
         @executor.create_partition(
           table_name,
           segment.name,
           segment.for_values_clause(strategy)
         )
+
+        unless Connection.partition_attached?(table_name, segment.name)
+          raise StandardError, "failed to attach planned partition #{segment.name} to #{table_name}"
+        end
       end
     end
 
@@ -205,8 +217,10 @@ module PartitionGardener
       operations.select { |operation| operation.action == :drop }.each do |operation|
         partition_name = operation.attached_segment.name
         next if Connection.partition_attached?(@config[:table_name], partition_name)
+        next unless Connection.partition_exists?(partition_name)
+        next unless Connection.count_rows_in_partition_table(partition_name).zero?
 
-        @executor.drop_table(partition_name) if Connection.partition_exists?(partition_name)
+        @executor.drop_table(partition_name)
       end
     end
 

data/lib/partition_gardener/sql_run_record_store.rb

@@ -1,6 +1,7 @@
 module PartitionGardener
   class SqlRunRecordStore
-    TABLE_NAME = "partition_gardener_run_records"
+    TABLE_NAME = "partition_gardener_checkpoints"
+    LEGACY_TABLE_NAMES = %w[partition_gardener_runs partition_gardener_run_records].freeze
 
     def initialize
       @schema_mutex = Mutex.new
@@ -40,6 +41,7 @@ module PartitionGardener
       @schema_mutex.synchronize do
         return if @schema_ready
 
+        migrate_legacy_table!
         connection.execute(create_table_sql)
         @schema_ready = true
       end
@@ -55,17 +57,50 @@ module PartitionGardener
       connection.quote_table_name(name)
     end
 
+    def storage_table_name
+      PartitionGardener.configuration.run_record_table_name
+    end
+
+    def migrate_legacy_table!
+      return unless storage_table_name == TABLE_NAME
+      return if catalog_relation_exists?(storage_table_name)
+
+      LEGACY_TABLE_NAMES.each do |legacy_name|
+        next if legacy_name == storage_table_name
+        next unless catalog_relation_exists?(legacy_name)
+
+        connection.execute(
+          "ALTER TABLE #{quoted_table(legacy_name)} RENAME TO #{quoted_table(storage_table_name)}"
+        )
+        break
+      end
+    end
+
+    def catalog_relation_exists?(name)
+      sql = <<~SQL
+        SELECT 1 AS present
+        FROM pg_catalog.pg_class AS classes
+        INNER JOIN pg_catalog.pg_namespace AS namespaces
+          ON namespaces.oid = classes.relnamespace
+        WHERE namespaces.nspname = #{connection.quote(PartitionGardener.configuration.schema_name)}
+          AND classes.relname = #{connection.quote(name)}
+          AND classes.relkind IN ('r', 'p')
+      SQL
+
+      Blank.present?(connection.execute(sql).first)
+    end
+
     def load_sql(table_name)
       <<~SQL
         SELECT table_name, phase, plan_signature, staging_row_count
-        FROM #{quoted_table(TABLE_NAME)}
+        FROM #{quoted_table(storage_table_name)}
         WHERE table_name = #{connection.quote(table_name)}
       SQL
     end
 
     def save_sql(table_name, attributes)
       <<~SQL
-        INSERT INTO #{quoted_table(TABLE_NAME)} (
+        INSERT INTO #{quoted_table(storage_table_name)} (
           table_name, phase, plan_signature, staging_row_count, updated_at
         ) VALUES (
           #{connection.quote(table_name)},
@@ -84,14 +119,14 @@ module PartitionGardener
 
     def clear_sql(table_name)
       <<~SQL
-        DELETE FROM #{quoted_table(TABLE_NAME)}
+        DELETE FROM #{quoted_table(storage_table_name)}
         WHERE table_name = #{connection.quote(table_name)}
       SQL
     end
 
     def create_table_sql
       <<~SQL
-        CREATE TABLE IF NOT EXISTS #{quoted_table(TABLE_NAME)} (
+        CREATE TABLE IF NOT EXISTS #{quoted_table(storage_table_name)} (
           table_name text PRIMARY KEY,
           phase text NOT NULL,
           plan_signature text NOT NULL,

data/lib/partition_gardener/version.rb

@@ -1,3 +1,3 @@
 module PartitionGardener
-  VERSION = "0.3.5"
+  VERSION = "0.3.7"
 end

data/sig/partition_gardener.rbs

@@ -3,10 +3,10 @@ module PartitionGardener
 
   MOVE_BATCH_SIZE: Integer
   FUTURE_MONTH_PARTITION_ROW_THRESHOLD: Integer
-  DEFAULT_STATEMENT_TIMEOUT: ActiveSupport::Duration
+  DEFAULT_STATEMENT_TIMEOUT: Integer
 
   def self.run!: (
-    ?statement_timeout: ActiveSupport::Duration,
+    ?statement_timeout: Integer | Numeric,
     ?job_class_name: String,
     ?continue_on_error: bool,
     ?dry_run: bool,