partition_gardener 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abde0192951f5cc668d53ca847f119c3d9dcf5c994404504119cfb1d54c6be17
-  data.tar.gz: 47eab4f81f45acf7a59730e2a04ac48769e655557da78c0db12be355a85ce6b2
+  metadata.gz: 168cd3dce806746b67801bac88f82c1bff76d9617aa7d11bb543a21476f92810
+  data.tar.gz: 3b89596e3ee530b5ea262b3d9e7e6396077b6198ad811951867e113e959c335a
 SHA512:
-  metadata.gz: 51677ad1c0b6d9513a86e574e9254776a7b9cecbd83f230a38b61d1a3f04be5313987901658aa9aebbf78e47a0f5ddd9b9573c6b3396c599ac6c60fdc932ab96
-  data.tar.gz: f1f4271c57f3a1ed9eaf2ca2f47d351cb50f729377f21bfac7657ce9d5342067b8dbc4c005d3db926d9cbf25186fbf0f431d287daf8139111758c2d647e7ac8d
+  metadata.gz: f55dcaca8b968cb74fbd77af80a7f8c14dbc7419274fdbbbab2fd0cfb11a2098e0a36b70908722180cbe344b87b18b532b68951e20be054cb1738c011566c009
+  data.tar.gz: f416553eda6be0049cc5dfdcd0fcbd4ef929c85b3e6411dc1fce3c210b87927f8ea846a6220705b7ca3ffc892b5539548eb5f342e8dd5b0f83324b68c6f5de7b

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.3.6 (2026-10-05)
+
+- Store rebalance checkpoints in `partition_gardener_checkpoints` by default (previously `partition_gardener_run_records`)
+- Add `run_record_table_name` so a host can keep another checkpoint table name
+- Rename leftover `partition_gardener_runs` or `partition_gardener_run_records` on first use of the default table name
+- Document public identifiers for partitioned rows: four contracts, Rails signed_id versus scalar primary_key, fail-closed decode ([application_contract.md](docs/application_contract.md#public-identifiers))
+
 ## 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`

data/README.md

@@ -37,7 +37,7 @@ Complements migration gems (e.g. [pg_party](https://github.com/rkrage/pg_party))
 ### 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, routing when the key is missing, bulk load, replicas
+- [docs/application_contract.md](docs/application_contract.md) — writes, moves, routing when the key is missing, public identifiers, 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
 

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.2.0	MIT
+root	parallel	2.1.0	MIT
 root	parser	3.3.12.0	MIT
-root	partition_gardener	0.3.5	MIT
+root	partition_gardener	0.3.6	MIT
 root	pg	1.6.3	BSD-2-Clause
-root	polyrun	2.2.4	MIT
+root	polyrun	2.2.3	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.7	MIT
+root	rack	3.2.6	MIT
 root	rainbow	3.1.1	MIT
 root	rake	13.4.2	MIT
 root	rbs	4.2.0	BSD-2-Clause|Ruby
@@ -35,7 +35,6 @@ 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.88.2	MIT
 root	rubocop-ast	1.50.0	MIT
 root	rubocop-capybara	2.23.0	MIT

data/docs/application_contract.md

@@ -1,6 +1,6 @@
 # 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).
+How host applications should behave around partitioned tables: queries, writes, public identifiers, 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
 
@@ -8,6 +8,7 @@ How host applications should behave around partitioned tables: queries, writes,
 - `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`.
 - When only a logical id or parent reference is available, follow the recovery ladder in [partition_landscape.md](partition_landscape.md#routing-hints-when-the-key-is-not-in-hand).
+- Public URLs and API ids follow [Public identifiers](#public-identifiers).
 - After maintenance with high `rows_moved`, refresh `id → partition_key` mappings when the partition key can change.
 
 ## During maintenance (row moves)
@@ -31,6 +32,31 @@ Duplicate key across children — overlapping manual DDL. Application response:
 
 Applications should not catch routing errors and retry without the partition key.
 
+## Public identifiers
+
+Treat database uniqueness, public identifier, routing hint, and authorization as four 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: `self.primary_key = :id` so `to_param` and JSON stay a scalar, not a Rails underscore composite 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 (`4_2`) or a separate query parameter the caller can edit independently.
+
+Prefer Rails APIs over a homemade encoding:
+
+- True composite `primary_key` (array): `signed_id` / `find_signed` or `to_sgid` / `SignedGlobalID`. Both uniqueness columns travel; `find` can prune. `signed_id` uses HMAC SHA256, JSON, and `url_safe: true`. The payload is encoded, not encrypted.
+- Scalar `primary_key = :id` plus `query_constraints`: `signed_id` and `generates_token_for` still sign and find by `id` alone. `query_constraints` never feeds `SELECT`. Sign `[id, partition_key]` with a host `ActiveSupport::MessageVerifier` (`url_safe: true`), or resolve through an unpartitioned mapping table.
+- `has_secure_token` stores a random Base58 mapping value. A unique index on that column alone is illegal on a partitioned parent unless the partition key is in the index. Put the mapping off the partitioned fact table, or keep a globally unique logical id on the fact row.
+- Default `MessageVerifier` is not URL-safe. `signed_id` and `GlobalID::Verifier` opt into `url_safe`. Do not encrypt identifiers with `MessageEncryptor`.
+- Unsigned GlobalID (`gid://app/Event/123/2026-03-15`) and `to_param` underscore composites are tunable. Keep them off public point-lookup URLs.
+- Extra JSON in `generates_token_for` is compared after fetch. It is not a `WHERE` predicate and is plaintext in the token.
+
+Active Record 7.1 is this gem's development floor. Composite `find_by_token_for` needs 7.2 or 8.0. Composite `find_signed` wrapping `primary_key => [id]` needs 8.1. Hosts on 7.1 should verify finders before relying on signed composite lookup.
+
+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. Encoding is packaging, not authorization. Lookups still go through an ownership set.
+
+List screens still show period, account, or branch in product language ([partition_landscape.md](partition_landscape.md#ui-and-product-surfaces)). Tenant and list keys for hot paths come from session or parent context, not from a tunable URL field. Pagination cursors already belong in the same family as opaque tokens.
+
+Gardener does not ship an encoder. Host applications own secrets, token version, and decode.
+
 ## Bulk import and backfill
 
 - Chunk `COPY` or `insert_all` by bucket window within partition bounds (month, week, day).
@@ -69,7 +95,7 @@ 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, or resolve through a mapping table before scanning children.
+- Global id search is an advanced, slow path; require date or tenant hint, or resolve through a mapping table before scanning children ([Public identifiers](#public-identifiers)).
 - 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)).
 
@@ -79,6 +105,6 @@ See [host_testing.md](host_testing.md) for CI registry fixtures and integration
 
 ## Related
 
-- [partition_landscape.md](partition_landscape.md) — pruning, routing layers and hints, UI, snapshots
+- [partition_landscape.md](partition_landscape.md) — pruning, routing layers and hints, UI, snapshots; `query_constraints` versus `SELECT`
 - [cutover.md](cutover.md) — backfill and switch
 - [naming.md](naming.md) — child table names

data/docs/audit_reference.md

@@ -98,7 +98,7 @@ Per-table metrics (`RunMetrics#to_h`):
 
 ## Run record table
 
-When `run_record_enabled`, PostgreSQL table `partition_gardener_run_records` stores:
+When `run_record_enabled`, PostgreSQL table `partition_gardener_checkpoints` (or `run_record_table_name`) stores:
 
 `table_name` — parent.
 

data/docs/changelogs/20260813142300_rebalance-before-archive-attach.md

@@ -0,0 +1,19 @@
+# Rebalance before archive attach
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Date-range maintenance rebalances the sliding-window tail before it finalizes monthly archives or applies retention. That lets one run detach a current partition that still starts on 1 July, attach a new current partition from 1 August, send July rows to default, and attach a non-overlapping monthly child from default.
+
+Archive attach is skipped when the bucket start is at or after the attached current partition lower bound. Those buckets wait until rebalance moves the current span forward. The lower bound is read with Connection.current_partition_lower_bound.
+
+## Effects
+
+A July-to-August maintenance sequence attaches the July monthly child and a current partition from 1 August.
+
+## Source
+
+Requested in the partition_gardener sliding-window rollover fix. Specs: spec/integration/sliding_window_maintenance_spec.rb and spec/partition_gardener/attach_retry_spec.rb.

data/docs/changelogs/20260813144516_relock-appraisal-advisory-json.md

@@ -0,0 +1,21 @@
+# Relock appraisal graphs for json advisory
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Appraisal lockfiles are part of the CI install graph. After 0.3.3 they must pin partition_gardener 0.3.3 and json 2.21.2 so frozen bundle install and bundle-audit both pass. The dependency audit workflow scans Gemfile.lock and *.gemfile.lock.
+
+## Effects
+
+Relocked gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby34.gemfile.lock, and gemfiles/rails8ruby4.gemfile.lock. Widened the find in .github/workflows/dependency-audit.yml.
+
+## Next
+
+Merge the patch so main test and dependency audit jobs install a consistent graph.
+
+## Source
+
+Triggered by failing Dependency audit and test workflows after the 0.3.3 merge. Advisory note: usr/docs/dependencies/20260813144516_json-cve-2026-71847.md.

data/docs/changelogs/20260902114500_align-child-columns-before-attach.md

@@ -0,0 +1,19 @@
+# Align child columns before attach
+
+## Participants
+
+Andrei
+
+## Decisions
+
+ATTACH PARTITION now runs additive column align first (default on). CREATE TABLE LIKE and DETACH snapshot columns; a later parent ADD COLUMN does not reach that child. Align adds all missing ordinary columns in one ALTER TABLE statement (skip identity and generated), preserving type, non-default collation, default, and NOT NULL. PostgreSQL rejects the complete statement when existing rows cannot satisfy NOT NULL, so standalone execution does not leave a partial alignment. Extra child columns stay. Existing types and other constraints are not rewritten.
+
+Audit warns when an unattached managed child still lags the parent. Built-in strategies filter unrelated prefixed tables and load all candidate column metadata in one catalog query. Custom partition name formatters retain prefix discovery because detached tables have no parent provenance. align_child_columns: false keeps fail-fast attach. JSON registry import rejects non-boolean align_child_columns values.
+
+## Effects
+
+LIKE and keep-table reattach paths attach after a parent ADD COLUMN without a host workaround. A missing conflict-key column is aligned before its child index is created.
+
+## Source
+
+https://github.com/amkisko/partition_gardener.rb/issues/18

data/docs/changelogs/20260902124500_cut-patch-release-0-3-4.md

@@ -0,0 +1,24 @@
+# Cut patch release 0.3.4
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Cut patch release 0.3.4 for child column align before ATTACH PARTITION, shipped after 0.3.3.
+
+## Effects
+
+Moved Unreleased notes into CHANGELOG.md under 0.3.4. Bumped lib/partition_gardener/version.rb and path-gem lockfiles to 0.3.4.
+
+## Next
+
+Merge trunk/0.3.4 to main, then run make release.
+
+## Source
+
+https://github.com/amkisko/partition_gardener.rb/issues/18
+https://github.com/amkisko/partition_gardener.rb/pull/19
+
+Feature note: usr/docs/changelogs/20260902114500_align-child-columns-before-attach.md

data/docs/changelogs/20260909143500_occupied-window-current-origin.md

@@ -0,0 +1,19 @@
+# Occupied window current origin
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Date-range planning keeps attached monthly children whose ranges overlap the active window. The remainder after a contiguous occupying prefix from the window start is named open. Current is reserved for a filler that starts at the window origin. OccupiedWindow reads Connection.attached_partitions bounds. ZoneSegments walks those catalog segments before heat splits and fillers. Monthly name parse also accepts an optional first-of-month suffix so those child names resolve as that month.
+
+A later pass changed the remainder name from current to open so the slot matches the documented origin rule.
+
+## Effects
+
+A monthly catalog through the current month no longer plans a current partition that overlaps the occupying child. Postgres attach of the remainder filler starts at the next month as open.
+
+## Source
+
+Follows usr/docs/issues/20260909143500_occupied-window-current-origin.md. Specs: spec/partition_gardener/date_range_occupied_window_spec.rb, spec/partition_gardener/sliding_window_spec.rb, spec/integration/sliding_window_maintenance_spec.rb.

data/docs/changelogs/20260909154900_tail-slot-rfc.md

@@ -0,0 +1,21 @@
+# Tail slot RFC
+
+## Participants
+
+Andrei
+
+## Decisions
+
+RFC 0001 records the project RFC process. RFC 0002 specifies occupancy-first tail slot names. A date-named child that covers a range is that range. Current, open, and future fill only uncovered ranges. Future starts after premade months that occupy keys at or after the window end. Registry flags are out of this RFC. A later pass dropped ensure_current, ensure_future, and ensure_default from the draft.
+
+## Effects
+
+rfcs/0001-rfc-process.md and rfcs/0002-tail-slots.md are Proposed. Occupied-window naming (open after an occupying origin) matches RFC 0002 current-zone occupancy. A later pass put high-end occupancy for future into the planner. Registry flags are not in this RFC.
+
+## Next
+
+Discuss RFC 0002 unresolved questions. Implementation PRs cite RFC-0002.
+
+## Source
+
+Follows usr/docs/issues/20260909143500_occupied-window-current-origin.md and rfcs/0002-tail-slots.md.

data/docs/changelogs/20260909162554_high-end-future-occupancy.md

@@ -0,0 +1,21 @@
+# High-end occupancy for future
+
+## Participants
+
+Andrei
+
+## Decisions
+
+A date-named child that covers keys at or after the active window end stays in the plan. Future starts after the latest finite end among those occupants. Future is omitted when an occupant already ends at MAXVALUE. Holes between those occupants stay gaps. Default remains residual routing. No registry flags.
+
+## Effects
+
+The sliding-window planner keeps a premade month that begins at the window end and starts future from the next month. A child that straddles the window end pushes future to that child's end. Noncontiguous premade months past the window stay attached. Apply no longer attaches future over a month that already occupies that range.
+
+## Next
+
+Discuss RFC 0002 unresolved questions. Integer-window occupancy is unchanged.
+
+## Source
+
+Follows rfcs/0002-tail-slots.md and usr/docs/issues/20260909143500_occupied-window-current-origin.md.

data/docs/changelogs/20260909164000_shipped-contract-rfcs.md

@@ -0,0 +1,21 @@
+# Shipped contract RFCs
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Stable RFCs 0003 through 0015 specify contracts that already ship: sliding window layout, registry JSON, plan and audit reports, archive names, retention, CLI, maintenance backends, keyset rebalance, advisory lock and run records, hot switch, child column align, integer window, and hash list composite. RFC 0001 and RFC 0002 stay Proposed. Integer occupancy stays unresolved inside RFC 0014. Registry flags for ensure slots stay out.
+
+## Effects
+
+rfcs/ids/0003 through rfcs/ids/0015 are claimed. Matching rfcs/NNNN-slug.md files are Stable. rfcs/README.md Current set lists them. CHANGELOG 0.3.5 records the set. Operator guides gained Related links. docs/cli.md apply --all example now includes --confirm.
+
+## Next
+
+Implementation PRs cite RFC-NNNN. Discuss RFC 0002 unresolved questions. Integer occupancy is a follow-on, not this set.
+
+## Source
+
+Follows the RFC 0002 occupancy-first work and the request to specify remaining shipped contracts under rfcs/.

data/docs/changelogs/20260909165500_cut-patch-release-0-3-5.md

@@ -0,0 +1,24 @@
+# Cut patch release 0.3.5
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Cut patch release 0.3.5 on main for occupancy-first sliding-window plans and RFCs 0001 through 0015, shipped after 0.3.4. Stay on main. No trunk branch.
+
+## Effects
+
+Moved Unreleased notes into CHANGELOG.md under 0.3.5. Bumped lib/partition_gardener/version.rb and path-gem lockfiles to 0.3.5.
+
+## Next
+
+Commit the version cut, then run make release.
+
+## Source
+
+Occupancy: usr/docs/changelogs/20260909143500_occupied-window-current-origin.md
+High-end future: usr/docs/changelogs/20260909162554_high-end-future-occupancy.md
+RFC 0002: usr/docs/changelogs/20260909154900_tail-slot-rfc.md
+Stable RFCs: usr/docs/changelogs/20260909164000_shipped-contract-rfcs.md

data/docs/changelogs/20260916144600_public-identifiers-contract.md

@@ -0,0 +1,23 @@
+# Public identifiers contract
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Host applications treat database uniqueness, public identifier, routing hint, and authorization as four contracts. When id is unique across children, keep a scalar application id and attach a routing hint on point lookups. When id is unique only inside a child, the public point-lookup identifier carries every uniqueness column as one opaque path segment.
+
+Prefer Rails signed_id or SignedGlobalID when primary_key is the composite array. When primary_key stays :id, sign [id, partition_key] with a host MessageVerifier or use an unpartitioned mapping table. query_constraints still only helps writes. Do not use to_param underscore form or unsigned GlobalID for public point lookups. Fail closed after decode. Browse screens still show period or tenant. Gardener does not ship an encoder.
+
+## Effects
+
+docs/application_contract.md gained a Public identifiers section. docs/partition_landscape.md Rails application contract, routing hints, and UI surfaces point to it. README application_contract blurb names public identifiers.
+
+## Next
+
+No RFC unless public identifiers become a gem runtime contract.
+
+## Source
+
+usr/docs/issues/20260916113300_opaque-composite-public-ids.md

data/docs/changelogs/20261005135700_checkpoint-table-name.md

@@ -0,0 +1,23 @@
+# Checkpoint table name
+
+## Participants
+
+Andrei
+
+## Decisions
+
+SqlRunRecordStore default table is partition_gardener_checkpoints. Hosts set run_record_table_name when they already own another relation. First use with the default name renames partition_gardener_runs or partition_gardener_run_records when that catalog relation exists and the default table does not.
+
+RFC 0011 records the table, the config key, and the rename.
+
+## Effects
+
+lib/partition_gardener/sql_run_record_store.rb and configuration.rb. Docs in configuration, operations, and audit_reference. Specs in sql_run_record_store_spec.rb.
+
+## Next
+
+Hosts that already created partition_gardener_run_records keep resume rows after the first enabled run, or set run_record_table_name to keep the old name.
+
+## Source
+
+RFC 0011

data/docs/changelogs/20261005141621_cut-patch-release-0-3-6.md

@@ -0,0 +1,23 @@
+# Cut patch release 0.3.6
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Cut patch release 0.3.6 on main for the default checkpoint table name, `run_record_table_name`, leftover table rename, and public identifier docs, shipped after 0.3.5. Stay on main. No trunk branch.
+
+## Effects
+
+Moved Unreleased notes into CHANGELOG.md under 0.3.6. Bumped lib/partition_gardener/version.rb and path-gem lockfiles to 0.3.6.
+
+## Next
+
+Run make release.
+
+## Source
+
+Checkpoint table: docs/changelogs/20261005135700_checkpoint-table-name.md
+Public identifiers: docs/changelogs/20260916144600_public-identifiers-contract.md
+RFC 0011

data/docs/configuration.md

@@ -47,6 +47,8 @@ When the gem loads inside Rails, the railtie sets `connection_resolver` and `tod
 
 `run_record_enabled` (default: `true`) — persist phase checkpoints for resume (global default).
 
+`run_record_table_name` (default: `partition_gardener_checkpoints`) — PostgreSQL table used by `SqlRunRecordStore`. On first use with the default name, the store renames `partition_gardener_runs` or `partition_gardener_run_records` when that relation exists and the default table does not.
+
 `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.
@@ -67,7 +69,7 @@ Do not run two full `run!` jobs against the same table concurrently. Host apps s
 
 ### 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`.
+When a database connection is configured (Active Record or `DATABASE_URL`), `SqlRunRecordStore` creates `partition_gardener_checkpoints` on first use. Checkpoints let incremental rebalance resume after partial failure. Disable with `config.run_record_enabled = false` or per-table `run_record_enabled: false`. Set `config.run_record_table_name` when the host already owns another table name.
 
 ## Per-table registration
 

data/docs/dependencies/20260813144516_json-cve-2026-71847.md

@@ -0,0 +1,27 @@
+# json CVE-2026-71847
+
+## Dependency
+
+json, pulled in through the development graph (rubocop / activesupport). Root Gemfile.lock already had 2.21.2 after the Dependabot bundler group bump. Appraisal locks gemfiles/rails72.gemfile.lock, gemfiles/rails8ruby34.gemfile.lock, and gemfiles/rails8ruby4.gemfile.lock still resolved 2.20.0.
+
+## Symptom
+
+bundle-audit check reports GHSA-9hj4-r449-hfvc / CVE-2026-71847 on json 2.20.0 through 2.21.1. The published fix is >= 2.21.2. Dependency audit CI on the 0.3.3 merge failed against the root lock while it still had 2.21.1. After Dependabot updated only Gemfile.lock, later audit jobs on main passed while the appraisal graphs CI actually installs stayed on 2.20.0. The audit workflow find matched files named Gemfile.lock only, so gemfiles/*.gemfile.lock were never scanned.
+
+Test CI on those same appraisal locks also failed in frozen mode because they still listed partition_gardener 0.3.2 after VERSION moved to 0.3.3.
+
+## Evidence
+
+Local bundle-audit check --gemfile-lock on each appraisal lock reported json 2.20.0 and the advisory. GitHub advisory: https://github.com/advisories/GHSA-9hj4-r449-hfvc. Upstream advisory: https://github.com/ruby/json/security/advisories/GHSA-9hj4-r449-hfvc. Failed Dependency audit run on the 0.3.3 merge: GitHub Actions run 31696494175.
+
+## Suggested fix
+
+Relock the three appraisal gemfiles so json is 2.21.2 and the path gem is 0.3.3. Teach .github/workflows/dependency-audit.yml to scan both Gemfile.lock and *.gemfile.lock.
+
+## Next
+
+Land the relock on main. Dependabot still watches only the root bundler directory, so appraisal graphs will need a manual relock when the next advisory lands unless that config grows.
+
+## Source
+
+Upstream: https://github.com/advisories/GHSA-9hj4-r449-hfvc and CVE-2026-71847. Downstream: gemfiles/*.gemfile.lock and .github/workflows/dependency-audit.yml on patch/relock-appraisal-advisory-json.

data/docs/issues/20260909143500_occupied-window-current-origin.md

@@ -0,0 +1,25 @@
+# Occupied monthly children at the active window start
+
+## Participants
+
+Andrei
+
+## Decisions
+
+When attached monthly children already cover the start of the sliding-window active range, the plan keeps those children and fills the remainder as open, not current. Current is only the filler that starts at the active window origin. The planner reads occupancy from attached range bounds, not only from parsed monthly names.
+
+Archive children whose range ends at or before the window start stay archive. Tail slot names current, open, and future are not occupancy. A first-month heat split that is not yet attached already named the later filler open; occupied prefix uses the same name.
+
+RFC 0002 records occupancy-first placement. A date-named child that covers a range is that range. Current, open, and future fill only uncovered ranges. Default is residual routing. This patch does not add registry flags. A later RFC 0002 pass dropped ensure flags from the draft and added high-end occupancy for future versus premade months past the window.
+
+## Effects
+
+A catalog of monthly children through the current month, with default only and no current or future slot, plans open from the next month and attaches without overlapping an existing child. A premade month that begins at the window end stays attached. Future starts after that month.
+
+## Next
+
+RFC 0002 stays Proposed. Unresolved questions live in the RFC, including integer occupancy. Implementation PRs cite RFC-0002.
+
+## Source
+
+Requested as a sliding-window plan fix after 0.3.3 skipped only the reverse overlap, archive attach when current already covers that month. Naming follow-up: current must not start after the occupying prefix.

data/docs/issues/20260909164000_shipped-contract-rfcs.md

@@ -0,0 +1,25 @@
+# Specify shipped contracts as Stable RFCs
+
+## Participants
+
+Andrei
+
+## Decisions
+
+Write Standards Track Stable RFCs for every shipped contract named in the RFC gap analysis, including layouts and execution paths that were previously operator-guide only. Skip whether-to-partition advice, engine recipes, monitoring SLOs, host CI, job wiring, and landscape UI notes. Skip registry ensure flags. Occupancy for integer catalogs stays an unresolved question, not a claimed walk.
+
+RFC numbers: 0003 sliding-window-layout, 0004 registry-json, 0005 plan-audit-reports, 0006 archive-naming, 0007 retention, 0008 cli, 0009 maintenance-backends, 0010 keyset-rebalance, 0011 advisory-lock-run-records, 0012 hot-switch, 0013 child-column-align, 0014 integer-window, 0015 hash-list-composite.
+
+Facts preserved: current is origin filler, not this month. Default is always created except hash. Apply always needs --confirm. Moves are insert then delete with ON CONFLICT. partition_key_column is trusted operator SQL.
+
+## Effects
+
+The RFC files and id claims exist on this branch. Indexes and Related links point at the set.
+
+## Next
+
+Review Proposed RFC 0002. Follow-on RFC if integer occupancy ships.
+
+## Source
+
+Requested after RFC 0001 and RFC 0002. Related usr/docs/changelogs/20260909164000_shipped-contract-rfcs.md.

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

@@ -0,0 +1,55 @@
+# Opaque composite public identifiers
+
+## Participants
+
+Andrei
+
+## 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
+
+- 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/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/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.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: partition_gardener
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Andrei Makarov
@@ -107,20 +107,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: rspec_junit_formatter
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.6'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.6'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
@@ -280,11 +266,28 @@ files:
 - docs/audit_reference.md
 - docs/background_job.md
 - docs/changelogs/20260709120900_partition-engines-guide.md
+- docs/changelogs/20260813142300_rebalance-before-archive-attach.md
+- docs/changelogs/20260813144516_relock-appraisal-advisory-json.md
+- docs/changelogs/20260902114500_align-child-columns-before-attach.md
+- docs/changelogs/20260902124500_cut-patch-release-0-3-4.md
+- docs/changelogs/20260909143500_occupied-window-current-origin.md
+- docs/changelogs/20260909154900_tail-slot-rfc.md
+- docs/changelogs/20260909162554_high-end-future-occupancy.md
+- docs/changelogs/20260909164000_shipped-contract-rfcs.md
+- docs/changelogs/20260909165500_cut-patch-release-0-3-5.md
+- docs/changelogs/20260916144600_public-identifiers-contract.md
+- docs/changelogs/20261005135700_checkpoint-table-name.md
+- docs/changelogs/20261005141621_cut-patch-release-0-3-6.md
 - docs/cli.md
 - docs/configuration.md
 - docs/cutover.md
 - docs/decision_flow.md
+- docs/dependencies/20260813144516_json-cve-2026-71847.md
 - docs/host_testing.md
+- docs/issues/20260909143500_occupied-window-current-origin.md
+- docs/issues/20260909164000_shipped-contract-rfcs.md
+- docs/issues/20260916113300_opaque-composite-public-ids.md
+- docs/issues/20260917123253_ci-drop-automatic-dependency-audit.md
 - docs/monitoring.md
 - docs/naming.md
 - docs/operations.md