partition_gardener 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4be8b78232ba13211d0baad009dea43f6320b96dd9b82398c8a4e86ed6008b3d
-  data.tar.gz: acb6c02d0192c07e3b8c9f959b6ada44e44014f9f5c144906e6649ebb1309e87
+  metadata.gz: abde0192951f5cc668d53ca847f119c3d9dcf5c994404504119cfb1d54c6be17
+  data.tar.gz: 47eab4f81f45acf7a59730e2a04ac48769e655557da78c0db12be355a85ce6b2
 SHA512:
-  metadata.gz: f387a844418342ef9f4ff644faf1ca2431f8259e3f26e9220bab9ce225ae5f1606ceb4651a94cb39f0e7929a7a0b7c2eae779c6aa7d079a8ad4355901f39a63f
-  data.tar.gz: a659acdb2ed364d72f44a9ecb0aab7ac925b27b77f8365e9da36582416145c9db9bbe6a1e9da279be036eab0cb4eda3d4a865d5a86a22741564bbcbf87145d32
+  metadata.gz: 51677ad1c0b6d9513a86e574e9254776a7b9cecbd83f230a38b61d1a3f04be5313987901658aa9aebbf78e47a0f5ddd9b9573c6b3396c599ac6c60fdc932ab96
+  data.tar.gz: f1f4271c57f3a1ed9eaf2ca2f47d351cb50f729377f21bfac7657ce9d5342067b8dbc4c005d3db926d9cbf25186fbf0f431d287daf8139111758c2d647e7ac8d

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.3.5 (2026-09-09)
+
+- Keep attached monthly children that already cover the start of the sliding-window active range, and fill the remainder as `_open` rather than overlapping `_current`
+- Start `_future` after premade months that occupy keys at or after the active window end, and skip `_future` when an occupying child already ends at MAXVALUE
+- Add the RFC process (RFC 0001) and a Proposed occupancy-first contract for `_current`, `_open`, and `_future` (RFC 0002)
+- Specify shipped registry, plan, CLI, layout, rebalance, lock, hot-switch, and column-align contracts as Stable RFCs 0003 through 0015
+
 ## 0.3.4 (2026-09-02)
 
 - Align LIKE and detached children with additive parent columns before `ATTACH PARTITION`, preserving type, collation, default, and `NOT NULL` atomically. Audit warns when a managed child still lags. Set `align_child_columns: false` to fail fast instead.

data/README.md

@@ -41,9 +41,10 @@ Complements migration gems (e.g. [pg_party](https://github.com/rkrage/pg_party))
 - [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
+### Schemas and RFCs
 
 - [docs/schemas/](docs/schemas/) — JSON schemas for registry and plan reports
+- [rfcs/](rfcs/) — design review; RFC 0002 Proposed tail slots; RFC 0003–0015 Stable shipped contracts
 
 ## Quick start
 

data/docs/THIRD_PARTY_LICENSE_MANIFEST.tsv

@@ -17,15 +17,15 @@ 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	parallel	2.2.0	MIT
 root	parser	3.3.12.0	MIT
-root	partition_gardener	0.3.4	MIT
+root	partition_gardener	0.3.5	MIT
 root	pg	1.6.3	BSD-2-Clause
-root	polyrun	2.2.3	MIT
+root	polyrun	2.2.4	MIT
 root	prism	1.9.0	MIT
 root	prosopite	2.2.0	Apache-2.0
 root	racc	1.8.1	Ruby|BSD-2-Clause
-root	rack	3.2.6	MIT
+root	rack	3.2.7	MIT
 root	rainbow	3.1.1	MIT
 root	rake	13.4.2	MIT
 root	rbs	4.2.0	BSD-2-Clause|Ruby

data/docs/audit_reference.md

@@ -122,6 +122,7 @@ Disable globally or per table if you do not want checkpoint storage ([configurat
 
 ## Related
 
+- [RFC 0005](../rfcs/0005-plan-audit-reports.md) — plan, audit, and RunSummary contract
 - [operations.md](operations.md) — remediation workflows
 - [monitoring.md](monitoring.md) — metrics from these fields
 - [naming.md](naming.md) — segment names in output

data/docs/cli.md

@@ -58,13 +58,14 @@ bundle exec partition_gardener --rails apply --confirm audits
 Apply all registered gardener-owned tables:
 
 ```bash
-bundle exec partition_gardener --rails apply --all
+bundle exec partition_gardener --rails apply --confirm --all
 ```
 
 Omitting a table name without `--all` also runs the full registry.
 
 ## Related
 
+- [RFC 0008](../rfcs/0008-cli.md) — verbs, confirm gate, table selection
 - [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

data/docs/configuration.md

@@ -257,6 +257,8 @@ Registry entries are operator-controlled configuration, not end-user input.
 
 ## Related
 
+- [RFC 0004](../rfcs/0004-registry-json.md) — portable registry file
+- [RFC 0009](../rfcs/0009-maintenance-backends.md) — gardener, pg_partman, hybrid
 - [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

data/docs/naming.md

@@ -8,13 +8,13 @@ Fixed suffixes on the parent table name:
 
 `{table}_default` — catch-all; must trend empty.
 
-`{table}_current` — start of active window.
+`{table}_current` — filler that starts at the active window origin. The span is the uncovered remainder of that window, not this calendar month or sequence id.
 
-`{table}_open` — gap filler in current zone.
+`{table}_open` — gap filler in the current zone when the origin is already a named child or a heat split. Extra fillers after that are `{table}_open_N`.
 
 `{table}_open_N` — extra fillers after heat splits.
 
-`{table}_future` — open-ended tail to MAXVALUE.
+`{table}_future` — open-ended tail to MAXVALUE. It starts at the first instant at or after the window end that no occupying child covers.
 
 `{table}_rebalance_staging` — temporary during tail rebalance.
 
@@ -66,6 +66,8 @@ Remediation: prefer `plan` + `apply` over manual attach. If manual children are
 
 ## Related
 
+- [RFC 0002](../rfcs/0002-tail-slots.md) — names and occupancy-first placement
+- [RFC 0006](../rfcs/0006-archive-naming.md) — date-bucket suffixes and parse-back
 - [operations.md](operations.md) — gap remediation
 - [cutover.md](cutover.md) — shadow `p_` prefix
 - [audit_reference.md](audit_reference.md) — gap messages

data/docs/retention.md

@@ -60,6 +60,7 @@ When `maintenance_backend: :pg_partman`, gardener skips the table; partman owns
 
 ## Related
 
+- [RFC 0007](../rfcs/0007-retention.md) — cutoff, preview, skip list
 - [decision_flow.md](decision_flow.md) — retention in layout choice
 - [operations.md](operations.md) — incident response
 - [monitoring.md](monitoring.md) — alerts

data/lib/partition_gardener/date_bucket.rb

@@ -101,7 +101,7 @@ module PartitionGardener
         match = partition_name.match(/^#{Regexp.escape(table_name)}_(\d{4})$/)
         return Date.new(match[1].to_i, 1, 1) if match
       else
-        match = partition_name.match(/^#{Regexp.escape(table_name)}_(\d{4})_(\d{2})$/)
+        match = partition_name.match(/^#{Regexp.escape(table_name)}_(\d{4})_(\d{2})(?:_01)?$/)
         return Date.new(match[1].to_i, match[2].to_i, 1) if match
       end
 

data/lib/partition_gardener/layout/calendar_year.rb

@@ -8,7 +8,7 @@ module PartitionGardener
           DateCalendar.add_years(active_start, active_years)
         end
 
-        def build_segments(config:, active_start:, active_end:, hot_years:)
+        def build_segments(config:, active_start:, active_end:, hot_years:, occupied_segments: [])
           strategy = Strategy::DateRange.new(config.merge(bucket: :year))
           buckets = strategy.send(:each_bucket_in_range, active_start, active_end)
 
@@ -19,7 +19,8 @@ module PartitionGardener
             active_start: active_start,
             active_end: active_end,
             hot_bucket_name: config[:partition_name_format],
-            bucket_end: ->(bucket) { DateCalendar.beginning_of_year(DateCalendar.next_year(bucket)) }
+            bucket_end: ->(bucket) { DateCalendar.beginning_of_year(DateCalendar.next_year(bucket)) },
+            occupied_segments: occupied_segments
           )
         end
       end

data/lib/partition_gardener/layout/occupied_window.rb

@@ -0,0 +1,86 @@
+module PartitionGardener
+  module Layout
+    module OccupiedWindow
+      module_function
+
+      def plan_segments(config:, window:, hot_buckets:, year_bucket:, tail_slot:)
+        occupied_segments = segments(table_name: config[:table_name], window: window, tail_slot: tail_slot)
+        layout_kwargs = {
+          config: config,
+          active_start: window[:start],
+          active_end: window[:end],
+          occupied_segments: occupied_segments
+        }
+
+        if year_bucket
+          CalendarYear.build_segments(**layout_kwargs, hot_years: hot_buckets)
+        else
+          SlidingWindow.build_segments(**layout_kwargs, hot_months: hot_buckets)
+        end
+      end
+
+      def segments(table_name:, window:, tail_slot:)
+        Connection.attached_partitions(table_name).filter_map do |partition|
+          next if partition.default
+          next if tail_slot.call(partition.name)
+          next unless overlap?(partition, window)
+
+          Plan::Segment.new(
+            name: partition.name,
+            range_start: partition.range_start,
+            range_end: partition.range_end,
+            kind: :hot_bucket
+          )
+        end.sort_by(&:range_start)
+      end
+
+      def overlap?(partition, window)
+        return false unless partition.range_start.is_a?(Date)
+        return false if partition.range_end.nil?
+        return true if partition.range_end == :max
+        return true if partition.range_end > window[:end]
+
+        partition.range_start < window[:end] && partition.range_end > window[:start]
+      end
+
+      def covering(occupied_segments, bucket)
+        occupied_segments.find do |segment|
+          next false if segment.range_start > bucket
+
+          segment.range_end == :max || segment.range_end > bucket
+        end
+      end
+
+      def next_bucket_index(buckets, bound, from:)
+        return buckets.length if bound == :max
+
+        index = from
+        index += 1 while index < buckets.length && buckets[index] < bound
+        index
+      end
+
+      def finish_with_high_end(segments, occupied_segments:, table_name:, active_end:)
+        leftover = occupied_segments.reject { |occupant| segments.any? { |segment| segment.name == occupant.name } }
+        leftover.each { |occupant| segments << occupant }
+
+        return segments if occupied_segments.any? { |segment| segment.range_end == :max }
+
+        segments << Plan::Segment.new(
+          name: Naming.future_partition_name(table_name),
+          range_start: future_start(occupied_segments, active_end),
+          range_end: :max,
+          kind: :future
+        )
+        segments
+      end
+
+      def future_start(occupied_segments, active_end)
+        later_ends = occupied_segments.filter_map do |segment|
+          segment.range_end if segment.range_end.is_a?(Date) && segment.range_end > active_end
+        end
+
+        [active_end, *later_ends].max
+      end
+    end
+  end
+end

data/lib/partition_gardener/layout/sliding_window.rb

@@ -7,7 +7,7 @@ module PartitionGardener
           DateBucket.add_buckets(active_start, span, bucket)
         end
 
-        def build_segments(config:, active_start:, active_end:, hot_months:)
+        def build_segments(config:, active_start:, active_end:, hot_months:, occupied_segments: [])
           strategy = Strategy::DateRange.new(config)
           buckets = strategy.send(:each_bucket_in_range, active_start, active_end)
           bucket = config.fetch(:bucket, :month)
@@ -19,7 +19,8 @@ module PartitionGardener
             active_start: active_start,
             active_end: active_end,
             hot_bucket_name: config[:partition_name_format],
-            bucket_end: ->(bucket_start) { DateBucket.end_of_bucket(bucket_start, bucket) }
+            bucket_end: ->(bucket_start) { DateBucket.end_of_bucket(bucket_start, bucket) },
+            occupied_segments: occupied_segments
           )
         end
       end

data/lib/partition_gardener/layout/zone_segments.rb

@@ -3,7 +3,7 @@ module PartitionGardener
     module ZoneSegments
       module_function
 
-      def build_filler_and_hot_segments(table_name:, buckets:, hot_buckets:, active_start:, active_end:, hot_bucket_name:, bucket_end:)
+      def build_filler_and_hot_segments(table_name:, buckets:, hot_buckets:, active_start:, active_end:, hot_bucket_name:, bucket_end:, occupied_segments: [])
         hot_bucket_set = hot_buckets.to_set
         segments = []
         middle_filler_index = 0
@@ -11,6 +11,13 @@ module PartitionGardener
 
         while index < buckets.length
           bucket = buckets[index]
+          occupant = OccupiedWindow.covering(occupied_segments, bucket)
+
+          if occupant
+            segments << occupant unless segments.any? { |segment| segment.name == occupant.name }
+            index = OccupiedWindow.next_bucket_index(buckets, occupant.range_end, from: index)
+            next
+          end
 
           if hot_bucket_set.include?(bucket)
             segments << Plan::Segment.new(
@@ -24,7 +31,7 @@ module PartitionGardener
           end
 
           run_start = bucket
-          while index < buckets.length && !hot_bucket_set.include?(buckets[index])
+          while index < buckets.length && !hot_bucket_set.include?(buckets[index]) && OccupiedWindow.covering(occupied_segments, buckets[index]).nil?
             index += 1
           end
           run_end = (index < buckets.length) ? buckets[index] : active_end
@@ -48,14 +55,12 @@ module PartitionGardener
           )
         end
 
-        segments << Plan::Segment.new(
-          name: Naming.future_partition_name(table_name),
-          range_start: active_end,
-          range_end: :max,
-          kind: :future
+        OccupiedWindow.finish_with_high_end(
+          segments,
+          occupied_segments: occupied_segments,
+          table_name: table_name,
+          active_end: active_end
         )
-
-        segments
       end
     end
   end

data/lib/partition_gardener/strategy/date_range.rb

@@ -25,22 +25,13 @@ module PartitionGardener
         window = active_window
         heatmap = collect_heatmap(window)
         hot_buckets = hot_buckets_in_window(heatmap, window)
-
-        segments = if year_bucket?
-          Layout::CalendarYear.build_segments(
-            config: @config,
-            active_start: window[:start],
-            active_end: window[:end],
-            hot_years: hot_buckets
-          )
-        else
-          Layout::SlidingWindow.build_segments(
-            config: @config,
-            active_start: window[:start],
-            active_end: window[:end],
-            hot_months: hot_buckets
-          )
-        end
+        segments = Layout::OccupiedWindow.plan_segments(
+          config: @config,
+          window: window,
+          hot_buckets: hot_buckets,
+          year_bucket: year_bucket?,
+          tail_slot: method(:tail_slot_name?)
+        )
 
         Plan::Result.new(segments: segments, hot_buckets: hot_buckets)
       end
@@ -231,6 +222,9 @@ module PartitionGardener
       def managed_tail_partition?(partition_name, window:)
         return true if tail_slot_name?(partition_name)
 
+        partition = Connection.attached_partitions(table_name).find { |item| item.name == partition_name }
+        return true if partition && Layout::OccupiedWindow.overlap?(partition, window)
+
         bucket = archive_bucket_from_partition_name(partition_name)
         bucket && bucket_in_window?(bucket, window)
       end

data/lib/partition_gardener/version.rb

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

data/lib/partition_gardener.rb

@@ -26,6 +26,7 @@ require_relative "partition_gardener/strategy/list_split"
 require_relative "partition_gardener/strategy/composite"
 require_relative "partition_gardener/strategy"
 require_relative "partition_gardener/layout/three_area"
+require_relative "partition_gardener/layout/occupied_window"
 require_relative "partition_gardener/layout/zone_segments"
 require_relative "partition_gardener/layout/sliding_window"
 require_relative "partition_gardener/layout/calendar_year"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: partition_gardener
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: ruby
 authors:
 - Andrei Makarov
@@ -317,6 +317,7 @@ files:
 - lib/partition_gardener/hash_routing.rb
 - lib/partition_gardener/layout/calendar_year.rb
 - lib/partition_gardener/layout/integer_window.rb
+- lib/partition_gardener/layout/occupied_window.rb
 - lib/partition_gardener/layout/sliding_window.rb
 - lib/partition_gardener/layout/three_area.rb
 - lib/partition_gardener/layout/zone_segments.rb