postburner 1.0.0.rc.5 → 1.0.0.rc.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 62187fb2fd681e87e1028c52cbd6f3756b32c895c05390bffca05d51e1287ec7
-  data.tar.gz: 31ab083d1e9d00bfb7dc6fabbf09d7065f5062d73a6cd738835a0b76f54426b6
+  metadata.gz: b48c13a76dd9b1b6e54f825bbc50d95574c0decd4a57b8b6ba3d3fc8c5ea369c
+  data.tar.gz: 5a867eef5d36cce234b2874b5c18ff95d0ddb648fd1576e71c0a8c5946ddc12c
 SHA512:
-  metadata.gz: d2e7a422e53852490b5e2ec8502f3dd69a34f17975ee808f463658f20f2ca228c5467d149987caaf7e905433b364b30c7f92142e07e7f7da3bbd7763d99c6284
-  data.tar.gz: aa6ce11d8f045be5b259a1869339117ddf40fca8e6d3579ced469355d2c89fbd7f19da96903154dac11a0f0efed57db840c1581ba9512c2665300d58d0453e32
+  metadata.gz: 82e60e8af9d983550d7a07dac46b1c5611eb11245944e2ddac5a7411cf2d0b63a59697cab1a83965379bb92c274c1abd33a1a475498f981cbcb8589d520ac61c
+  data.tar.gz: 430829a786da22122f8ce4a47e8e966feb524877539f7a0e4086db912731235064c6888d0662d67c438e0c2e2d590a2a4496e33a56658b3022f70fbbb58ca050

data/CHANGELOG.md

@@ -1,5 +1,81 @@
 # Changelog
 
+## v1.0.0.rc.6 - 2026-06-27
+
+### Highlights
+
+- `Postburner::Schedule#reconcile!` — guarantees exactly one live future execution per enabled schedule and zero future executions for a disabled schedule. The watchdog delegates to it.
+- `Postburner::Schedule#enable!` / `#disable!` — convenience wrappers that drive reconciliation.
+- Auto-reconcile on schedule edits — an `after_update_commit` hook reconciles whenever a scheduling/snapshot attribute changes.
+- `Postburner::ScheduleExecution#supersede!` — tears down an execution (Beanstalkd job + `Postburner::Job` AR row) and marks it `superseded`.
+- `superseded` status (enum value `201`) on `Postburner::ScheduleExecution`, distinct from `skipped`. Neither counts as a live future execution.
+- `live` and `future_live` scopes on `Postburner::ScheduleExecution` (`pending`/`scheduled` only; `future_live` adds `run_at > now`).
+- Instrumentation events `supersede.schedule_execution.postburner` and `reconcile.schedule.postburner`.
+- **`ScheduleExecution#skip!` now skips one occurrence, then resumes -- tearing down down the associated `Postburner::Job` **and** the Beanstalkd job. The skipped row is retained as history.
+- **`schedule.destroy` now tears down each execution's Beanstalkd job and `Postburner::Job` (no orphans)
+- The watchdog sweeps **disabled** schedules with a lingering live future execution and supersedes them.
+
+### Fixed
+
+- Scheduled **tracked ActiveJob** executions had a `nil` `bkid`: the adapter stored the entire Beanstalkd put response hash (`{status:, id:}`) instead of the id, which cast to `nil` in the `bigint` column. Scheduled **non-tracked ActiveJob** executions discarded the Beanstalkd id entirely (`beanstalk_job_id` was always `nil`), so they could not be cancelled. Both now capture the real id via the adapter's `provider_job_id`.
+- Scheduled **`Postburner::Job`** executions stored the wrong value in `ScheduleExecution#beanstalk_job_id` (the return value of `queue!`, not the Beanstalkd id). It now holds the real `job.bkid`.
+- `Postburner::OrphanedJob#destroy` can be soft-removed (`remove!`) and destroyed (`destroy`), with Beanstalkd job, while `readonly?` still blocks changes.
+
+### Upgrade notes
+
+- This is a **template mutation** (like rc.4), not an additive migration. Existing installs must add a migration that:
+  1. Replaces the total unique index on `(schedule_id, run_at)` with a **live-only partial** unique index (`WHERE status IN (0, 11)`), so a superseded/skipped row can coexist with a freshly recreated live execution at the same `run_at`.
+  2. Drops `ON DELETE CASCADE` on the `schedule_id` foreign key (teardown is now owned by `dependent: :destroy` + `before_destroy`).
+- **Behavior change — deleting a schedule.** With `ON DELETE CASCADE` removed, deleting a schedule by any path other than ActiveRecord `destroy` — raw SQL, `Schedule.delete`, `where(...).delete_all` — now raises a foreign-key violation when the schedule has executions, instead of silently cascading. Always use `schedule.destroy` (which runs `dependent: :destroy` + the `before_destroy` teardown). This is intentional: it prevents orphaned Beanstalkd jobs and `Postburner::Job` rows.
+
+Standalone upgrade migration (written for zero-downtime on large `postburner_schedule_executions` tables — builds the index `CONCURRENTLY` and adds the FK unvalidated then validates it, neither of which blocks writes; requires `disable_ddl_transaction!`):
+
+```ruby
+class UpgradePostburnerSchedulesForReconcile < ActiveRecord::Migration[7.2]
+  disable_ddl_transaction!
+
+  # Existing installs created the unique index via the generator with Rails'
+  # default name. Adjust if your install named it differently.
+  OLD_INDEX = 'index_postburner_schedule_executions_on_schedule_id_and_run_at'
+  NEW_INDEX = 'index_pb_sched_exec_live_schedule_run_at'
+
+  def up
+    # 1. Add the live-only partial unique index CONCURRENTLY (no write lock) so a
+    #    superseded/skipped row can coexist with a live recreate at the same run_at.
+    #    Narrowing uniqueness can't conflict with existing data (the old total
+    #    index was stricter), so this build cannot fail on valid rows.
+    add_index :postburner_schedule_executions, [:schedule_id, :run_at],
+      unique: true, where: 'status IN (0, 11)',
+      name: NEW_INDEX, algorithm: :concurrently, if_not_exists: true
+
+    # Drop the old total unique index. Target by NAME: with the new index added,
+    # two indexes now match the (schedule_id, run_at) columns.
+    remove_index :postburner_schedule_executions,
+      name: OLD_INDEX, algorithm: :concurrently, if_exists: true
+
+    # 2. Replace the cascading FK with a plain one. Add unvalidated first (brief
+    #    metadata-only lock), then validate separately (does not block writes).
+    #    dependent: :destroy + before_destroy now own teardown.
+    remove_foreign_key :postburner_schedule_executions, column: :schedule_id
+    add_foreign_key :postburner_schedule_executions, :postburner_schedules,
+      column: :schedule_id, validate: false
+    validate_foreign_key :postburner_schedule_executions, column: :schedule_id
+  end
+
+  def down
+    remove_foreign_key :postburner_schedule_executions, column: :schedule_id
+    add_foreign_key :postburner_schedule_executions, :postburner_schedules,
+      column: :schedule_id, on_delete: :cascade, validate: false
+    validate_foreign_key :postburner_schedule_executions, column: :schedule_id
+
+    add_index :postburner_schedule_executions, [:schedule_id, :run_at],
+      unique: true, name: OLD_INDEX, algorithm: :concurrently, if_not_exists: true
+    remove_index :postburner_schedule_executions,
+      name: NEW_INDEX, algorithm: :concurrently, if_exists: true
+  end
+end
+```
+
 ## v1.0.0.rc.5 - 2026-06-26
 
 ### Fixed

data/README.md

@@ -126,7 +126,7 @@ Postburner [beanstalkd](https://beanstalkd.github.io/) is used with PostgreSQL t
 
 ```ruby
 # Gemfile
-gem 'postburner', '~> 1.0.0.pre.18'
+gem 'postburner', '~> 1.0.0.rc.6'
 
 # config/application.rb
 config.active_job.queue_adapter = :postburner
@@ -499,8 +499,7 @@ The scheduler uses **immediate enqueue** combined with a **watchdog safety net**
    ```
 4. When a worker reserves the watchdog, it instantiates `Postburner::Scheduler` which:
    - Acquires a PostgreSQL advisory lock for coordination
-   - Auto-bootstraps any unstarted schedules
-   - Ensures each schedule has a future execution queued
+   - Reconciles every schedule (see [Editing & Pausing Schedules](#editing--pausing-schedules)) — auto-bootstrapping unstarted schedules, ensuring each enabled schedule has exactly one future execution queued, and tearing down lingering futures on disabled schedules
    - Re-queues a new watchdog with delay for the next interval
 
 NOTE: The watchdog is ephemeral data in Beanstalkd, not a database record. `Postburner::Scheduler` is the handler class that does the work. This design requires no dedicated scheduler process - existing workers handle everything.
@@ -687,8 +686,9 @@ Postburner::Schedule.create!(
 schedule = Postburner::Schedule.find_by(name: 'daily_cleanup')
 Postburner::Schedule.enabled  # All enabled schedules
 
-# Disable temporarily
-schedule.update!(enabled: false)
+# Pause / resume (preferred — see "Editing & Pausing Schedules" below)
+schedule.disable!  # Tears down the queued future execution
+schedule.enable!   # Resumes from the next grid point after now
 
 # Change catch-up policy
 schedule.update!(catch_up: true)
@@ -700,11 +700,68 @@ schedule.next_run_at  # => 2025-01-02 09:00:00 -0500
 schedule.next_run_at_times(5)  # Next 5 run times
 
 # View executions
+schedule.executions.live        # pending + scheduled (real queued work)
+schedule.executions.future_live # the live future execution(s)
 schedule.executions.pending
 schedule.executions.scheduled
-schedule.executions.skipped
+schedule.executions.skipped     # cancelled occurrences (history)
+schedule.executions.superseded  # replaced by a recreate (history)
+
+# Delete a schedule (ALWAYS use destroy — see note below)
+schedule.destroy  # Tears down every execution's Beanstalkd job + Postburner::Job row
 ```
 
+**Deleting schedules — always use `destroy`.** `schedule.destroy` runs `dependent: :destroy` plus a `before_destroy` teardown that removes each execution's Beanstalkd job and any `Postburner::Job` row, so nothing is orphaned. Deleting a schedule by any other path — raw SQL, `Schedule.delete`, `where(...).delete_all` — raises a foreign-key violation when the schedule has executions, by design. Reach for `schedule.destroy` (or `disable!` to keep the record and history).
+
+#### Editing & Pausing Schedules
+
+Postburner keeps a schedule's queued work in sync with its configuration through a single, idempotent convergence path: **reconciliation**. The guarantee is simple:
+
+- An **enabled** schedule always has **exactly one** live future execution, sitting on the current grid with a snapshot matching the live config.
+- A **disabled** schedule has **zero** future executions.
+
+You rarely call reconciliation directly (`schedule.reconcile!` exists if you need it). Instead it runs for you in three places: the watchdog reconciles every schedule on each pass, schedule edits trigger it automatically, and `enable!` / `disable!` drive it.
+
+##### Pausing & resuming
+
+Use `disable!` / `enable!` rather than `update!(enabled: ...)` (both work, but these read better and make intent obvious):
+
+```ruby
+schedule.disable!  # Supersedes the queued future execution → zero future executions
+schedule.enable!   # Recreates a future execution at the next grid point after now
+```
+
+Disabling now actually tears down the queued future execution in Beanstalkd — it doesn't just stop creating new ones. Enabling resumes from the **next grid point after now**; it does **not** backfill the gap while the schedule was paused (`catch_up` only governs the running-job chaining path, not resume).
+
+##### Editing a schedule
+
+Editing a scheduling/snapshot attribute — `args`, `queue`, `priority`, the grid (`anchor`, `interval`, `interval_unit`, `cron`), `timezone`, `enabled`, or `name` — automatically supersedes the stale queued execution and recreates it from the current config (via an `after_update_commit` hook):
+
+```ruby
+# Payload-only edit: recreates the future execution at the SAME run_at
+schedule.update!(args: { report_type: 'weekly' })
+
+# Grid edit: recreates the future execution at the NEW grid point
+schedule.update!(interval: 2, interval_unit: 'hours')
+```
+
+> **Best-effort, not synchronous.** This inline reconcile is non-blocking: it *tries* the global scheduler advisory lock without waiting, so it never holds up a web request. If the watchdog happens to hold the lock mid-sweep, the inline reconcile is skipped and the watchdog converges on its next pass. For UI-managed schedules, **don't assume the next run is updated immediately** — read it back after the watchdog interval (`scheduler_interval`) rather than right after the save.
+
+##### Skipping a single occurrence
+
+`skip!` cancels **one** upcoming occurrence and then resumes at the next grid point after the skipped slot. It tears down both the Beanstalkd job and the associated `Postburner::Job` row, marks the execution `skipped` (kept as history), and triggers a best-effort reconcile. The skipped occurrence does not run and is not recreated:
+
+```ruby
+execution = schedule.executions.future_live.first
+execution.skip!  # This one won't run; the schedule continues at the next grid point
+```
+
+To pause every upcoming run instead of just one, use `disable!`.
+
+##### Superseding (internal)
+
+`ScheduleExecution#supersede!` performs the same teardown as `skip!` but records a `superseded` status, meaning the execution was replaced by a recreate (config/grid drift resolved by reconciliation) rather than cancelled by an operator. Reconciliation uses it internally; you'll mostly encounter `superseded` rows when reading execution history. Like skipped rows, superseded rows are excluded from `live` / `future_live`.
+
 #### Starting Schedules
 
 When you create a schedule, it won't run until the first execution is created. You have two options:
@@ -748,19 +805,27 @@ Each scheduled run creates an execution record for tracking:
 ```ruby
 execution = Postburner::ScheduleExecution.find(123)
 
-execution.status        # pending, scheduled, skipped
+execution.status        # pending, scheduled, skipped, superseded
 execution.run_at        # Scheduled time
 execution.enqueued_at   # When job was queued
 execution.beanstalk_job_id  # Beanstalkd job ID
 execution.job_id            # Postburner::Job ID (if using Postburner::Job)
 ```
 
+**Status values:**
+- `pending` — created, not yet enqueued to Beanstalkd
+- `scheduled` — enqueued to Beanstalkd, waiting for `run_at`
+- `skipped` — one occurrence cancelled by an operator (`skip!`); retained as history
+- `superseded` — replaced by a recreate during reconciliation (`supersede!`); retained as history
+
+Only `pending` and `scheduled` count as a live future execution (the `live` / `future_live` scopes). `skipped` and `superseded` are inert history.
+
 **Execution lifecycle:**
 1. Execution created with `pending` status and immediately enqueued to Beanstalkd
 2. Status changes to `scheduled` once enqueued
 3. At `run_at` time, Beanstalkd releases job to worker
 4. For `Postburner::Job` (and `ActiveJob` with `Postburner::Tracked`) schedules: `before_attempt` callback creates next execution
-5. Watchdog periodically verifies future executions exist (safety net)
+5. Watchdog periodically reconciles each schedule, guaranteeing future executions exist (safety net)
 
 #### Timezone Handling
 
@@ -1572,7 +1637,8 @@ Postburner emits ActiveSupport::Notifications events following Rails conventions
 |-------|------|--------------|
 | `create.schedule.postburner` | When schedule is created | `:schedule` |
 | `update.schedule.postburner` | When schedule is updated | `:schedule`, `:changes` |
-| `audit.schedule.postburner` | When scheduler audits a schedule | `:schedule` |
+| `audit.schedule.postburner` | When scheduler audits a schedule | `:schedule`, `:execution_created`, `:orphans_enqueued` |
+| `reconcile.schedule.postburner` | When a schedule is reconciled (executions converged to config) | `:schedule`, `:superseded`, `:created` |
 
 **Schedule Payload Structure:**
 
@@ -1595,7 +1661,8 @@ Postburner emits ActiveSupport::Notifications events following Rails conventions
 |-------|------|--------------|
 | `create.schedule_execution.postburner` | When execution is created | `:schedule`, `:execution` |
 | `enqueue.schedule_execution.postburner` | When execution is enqueued to Beanstalkd | `:schedule`, `:execution`, `:beanstalk_job_id` |
-| `skip.schedule_execution.postburner` | When execution is skipped | `:schedule`, `:execution` |
+| `skip.schedule_execution.postburner` | When an operator skips one occurrence | `:schedule`, `:execution` |
+| `supersede.schedule_execution.postburner` | When an execution is superseded (replaced by a recreate during reconciliation) | `:schedule`, `:execution` |
 
 **Execution Payload Structure:**
 
@@ -2368,7 +2435,7 @@ Key changes in v1.0:
 
 1. **Update Gemfile:**
    ```ruby
-   gem 'postburner', '~> 1.0.0.pre.18'
+   gem 'postburner', '~> 1.0.0.rc.6'
    ```
 
 2. **Remove Backburner config:**

data/app/models/postburner/orphaned_job.rb

@@ -84,6 +84,10 @@ module Postburner
     # through instance save/update and therefore does not trigger
     # `ensure_proper_type` either).
     #
+    # Uses the STI base class for the relation so the row's missing `type` value
+    # (which differs from OrphanedJob's sti_name) does not scope it out — a
+    # `self.class.where` would match zero rows and silently fail to persist.
+    #
     # Idempotent: does nothing if already removed.
     #
     # @return [void]
@@ -93,10 +97,31 @@ module Postburner
 
       self.delete!
       now = Time.current
-      self.class.where(id: self.id).update_all(removed_at: now)
+      self.class.base_class.where(id: self.id).update_all(removed_at: now)
       self.removed_at = now
     end
 
+    # Hard-deletes this orphaned row, removing BOTH its Beanstalkd job and its AR
+    # row, while keeping `readonly?` true for saves/updates.
+    #
+    # The base ActiveRecord#destroy raises ReadOnlyRecord on a readonly record,
+    # which would make ScheduleExecution#teardown_job! (which calls `job.destroy`
+    # uniformly across job shapes) fail for an execution whose job class was
+    # deleted/renamed. This override mirrors {#remove!}: it removes the Beanstalkd
+    # job via {#delete!} and deletes the row at the relation level — using the STI
+    # base class so the missing `type` value doesn't scope the row out — bypassing
+    # both `readonly?` and instance callbacks. The row is genuinely removed (not a
+    # soft-delete), matching destroy semantics.
+    #
+    # @return [self] frozen, with destroyed? == true
+    #
+    def destroy
+      self.delete!
+      self.class.base_class.where(id: self.id).delete_all
+      @destroyed = true
+      freeze
+    end
+
     # Prevents saves that would allow Rails' ensure_proper_type to overwrite the
     # original `type` value with 'Postburner::OrphanedJob'.
     #

data/app/models/postburner/schedule.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'postburner/advisory_lock'
+
 module Postburner
   # Schedule model for recurring job execution with fixed-rate, grid-aligned scheduling.
   #
@@ -118,6 +120,21 @@ module Postburner
     after_create_commit :instrument_create
     after_update_commit :instrument_update
 
+    # Reconcile executions whenever a relevant attribute changes.
+    #
+    # Runs post-commit (so enqueueing to Beanstalkd is safe and observes the
+    # committed config) and only when a config attribute that affects scheduling
+    # or the cached snapshot actually changed. reconcile! mutates executions and
+    # uses update_column for last_audit_at, so it never re-triggers this callback.
+    after_update_commit :reconcile_after_change
+
+    # Schedule attributes whose change should trigger reconciliation. Mirrors the
+    # cacheable_attributes set plus :enabled (enable/disable drives reconcile).
+    RECONCILE_TRIGGER_ATTRS = %w[
+      enabled job_class args queue priority timezone
+      anchor interval interval_unit cron catch_up name
+    ].freeze
+
     # Scopes
     scope :enabled, -> { where(enabled: true) }
     scope :disabled, -> { where(enabled: false) }
@@ -183,7 +200,11 @@ module Postburner
     #   will return nil with a warning logged.
     #
     def create_next_execution!(after: nil)
-      # Check if a future execution already exists (any status - including skipped).
+      # Check if a LIVE future execution already exists.
+      #
+      # Only pending/scheduled rows count: a skipped or superseded row must NOT
+      # block creation of the next live future, so this matches the same
+      # "live future" notion reconcile! and future_live use.
       #
       # TIME PRECISION: When called from a job callback during time travel
       # (e.g., ImmediateTestQueue), Time.current and execution.run_at can differ
@@ -197,7 +218,7 @@ module Postburner
       # after.run_at when an execution is provided, we correctly exclude the
       # current execution from the future check.
       check_time = after.is_a?(ScheduleExecution) ? after.run_at : Time.current
-      return nil if executions.where('run_at > ?', check_time).exists?
+      return nil if executions.live.where('run_at > ?', check_time).exists?
 
       # Determine base time for calculating next execution.
       #
@@ -217,7 +238,15 @@ module Postburner
                      Time.current
                    end
 
-      create_execution!(after: after_time)
+      # Compute the next slot from the chosen base time using the SAME skip-aware
+      # computation reconcile! uses, so the before_attempt chaining path can never
+      # place a live execution onto a grid point that carries a skipped (cancelled)
+      # occurrence. With no skipped slots this is identical to the next grid point
+      # strictly after `after_time` (i.e. unchanged behavior).
+      desired = next_grid_point_skipping_cancelled(after: after_time)
+      return nil if desired.nil?
+
+      create_execution!(at: desired)
     rescue ActiveRecord::RecordNotUnique, ActiveRecord::RecordInvalid => e
       # Race condition - another process/thread created it between our check and insert
       # RecordNotUnique: PostgreSQL constraint violation
@@ -226,6 +255,73 @@ module Postburner
       nil
     end
 
+    # Converge this schedule's executions to its target invariants. Idempotent.
+    #
+    # This is the single convergence path that owns:
+    #   1. exactly one LIVE future execution per ENABLED schedule,
+    #   2. zero future executions for a DISABLED schedule,
+    #   3. the future execution sits on the current grid with a non-drifted
+    #      cached snapshot.
+    #
+    # Always future-only: it never touches past or in-flight executions. Always
+    # resumes from the next grid point after now; it does NOT honor catch_up to
+    # backfill a gap (that is the before_attempt chaining path's concern, not
+    # reconcile's).
+    #
+    # Concurrency: mutual exclusion is provided by the SCHEDULER_LOCK_KEY advisory
+    # lock (NOT a wrapping AR transaction, so enqueue can happen after commit).
+    # Each supersede!/create runs in its own small transaction; the live-only
+    # partial unique index on (schedule_id, run_at) is the hard backstop.
+    #
+    # @param lock [Boolean] acquire SCHEDULER_LOCK_KEY. Pass false when the caller
+    #   (the watchdog) already holds it.
+    # @param blocking [Boolean] when acquiring the lock, wait for it (true) or give
+    #   up immediately if it's held (false). Admin-triggered paths (skip!, the
+    #   after_update_commit edit hook) pass false so a web request never blocks for
+    #   the duration of a watchdog sweep — if the lock is busy they skip the inline
+    #   reconcile and let the watchdog converge on its next pass. Ignored when
+    #   lock: false.
+    # @return [ScheduleExecution, nil] the execution created this run, or nil if
+    #   the schedule was already stable/disabled OR (non-blocking) the lock was
+    #   held. Callers use this to populate the `execution_created` instrumentation
+    #   key.
+    #
+    def reconcile!(lock: true, blocking: true)
+      return reconcile_unlocked! unless lock
+
+      acquired = false
+      result = Postburner::AdvisoryLock.with_lock(
+        Postburner::AdvisoryLock::SCHEDULER_LOCK_KEY, blocking: blocking
+      ) do
+        acquired = true
+        reconcile_unlocked!
+      end
+
+      unless acquired
+        Rails.logger.debug(
+          "[Postburner::Schedule] reconcile! skipped for '#{name}': scheduler lock " \
+          "held; the watchdog will converge on its next pass"
+        )
+      end
+
+      result
+    end
+
+    # Enable this schedule (and reconcile via after_update_commit).
+    #
+    # @return [Boolean]
+    def enable!
+      update!(enabled: true)
+    end
+
+    # Disable this schedule (and reconcile via after_update_commit, which
+    # supersedes the future execution so zero future executions remain).
+    #
+    # @return [Boolean]
+    def disable!
+      update!(enabled: false)
+    end
+
     # Calculate next N run times.
     #
     # Uses either cron or anchor-based calculation depending on schedule mode.
@@ -336,7 +432,12 @@ module Postburner
         queue: queue,
         priority: priority,
         timezone: timezone,
-        anchor: anchor,
+        # Emit anchor as a deterministic ISO-8601 string (ms precision) rather
+        # than a raw Time, so the cached snapshot and a live cacheable_attributes
+        # hash compare equal under ScheduleExecution#drifted? without a
+        # Time-vs-string false drift. Anchors are second/minute aligned in
+        # practice, so millisecond precision is more than sufficient.
+        anchor: anchor&.iso8601(3),
         interval: interval,
         interval_unit: interval_unit,
         cron: cron,
@@ -346,6 +447,131 @@ module Postburner
 
     private
 
+    # The reconciliation algorithm, assuming the caller holds SCHEDULER_LOCK_KEY.
+    #
+    # @return [ScheduleExecution, nil] the created execution, or nil
+    #
+    # @api private
+    #
+    def reconcile_unlocked!
+      live = executions.future_live.to_a
+
+      unless enabled?
+        # Invariant 2: a disabled schedule has zero future executions.
+        live.each(&:supersede!)
+        touch_audit!
+        instrument_reconcile(superseded: live.size, created: false)
+        return nil
+      end
+
+      # The next grid point after now that we should occupy. Advance past any
+      # grid point that was explicitly SKIPPED: a skipped occurrence is cancelled
+      # and must not be recreated. (A superseded slot, by contrast, IS
+      # recreatable — payload-drift recreates at the same run_at — so it must not
+      # be skipped past.)
+      desired = next_grid_point_skipping_cancelled
+
+      current = live.first
+
+      # Stable when there is exactly one live future, it sits on the desired grid
+      # point, and its cached snapshot matches the live config.
+      stable = live.size == 1 &&
+               desired.present? &&
+               current.run_at.to_i == desired.to_i &&
+               !current.drifted?(self)
+
+      if stable
+        touch_audit!
+        instrument_reconcile(superseded: 0, created: false)
+        return nil
+      end
+
+      # Free the live slot(s).
+      live.each(&:supersede!)
+
+      # If the schedule has no more grid points, create nothing.
+      if desired.nil?
+        touch_audit!
+        instrument_reconcile(superseded: live.size, created: false)
+        return nil
+      end
+
+      # Recreate exactly one live future at the desired grid point.
+      created = create_execution!(at: desired)
+      touch_audit!
+      instrument_reconcile(superseded: live.size, created: created.present?)
+      created
+    end
+
+    # The next grid point strictly after `after`, advanced past any grid point
+    # that already has a SKIPPED execution (a cancelled occurrence must not be
+    # recreated). A SUPERSEDED slot is NOT skipped — it remains recreatable at the
+    # same run_at (payload-drift recreate). Returns nil if the schedule has no
+    # further grid points.
+    #
+    # This is the single skip-aware "next occurrence" computation shared by both
+    # reconcile! (after: Time.current) and the before_attempt chaining path
+    # (create_next_execution!), so neither can place a live execution onto a
+    # skipped slot.
+    #
+    # @param after [Time] base time to calculate the next grid point after
+    #   (default: Time.current, preserving reconcile!'s behavior)
+    # @return [Time, nil]
+    #
+    # @api private
+    #
+    def next_grid_point_skipping_cancelled(after: Time.current)
+      desired = next_run_at(after: after)
+      while desired && executions.skipped.exists?(run_at: desired)
+        nxt = next_run_at(after: desired)
+        break if nxt.nil? || nxt.to_i <= desired.to_i # guard against non-advancing grids
+        desired = nxt
+      end
+      desired
+    end
+
+    # Update last_audit_at without firing after_update_commit (which would
+    # otherwise re-trigger reconcile_after_change).
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def touch_audit!
+      update_column(:last_audit_at, Time.current)
+    end
+
+    # after_update_commit hook: reconcile only when a scheduling/snapshot
+    # attribute actually changed.
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def reconcile_after_change
+      return if (saved_changes.keys & RECONCILE_TRIGGER_ATTRS).empty?
+
+      # Best-effort: never block a web request on the global scheduler lock. If the
+      # watchdog is mid-sweep, skip the inline reconcile; the watchdog converges.
+      reconcile!(blocking: false)
+    end
+
+    # Instrument a reconcile run.
+    #
+    # @param superseded [Integer] number of executions superseded this run
+    # @param created [Boolean] whether a new execution was created this run
+    # @return [void]
+    #
+    # @api private
+    #
+    def instrument_reconcile(superseded:, created:)
+      ActiveSupport::Notifications.instrument('reconcile.schedule.postburner', {
+        schedule: Postburner::Instrumentation.schedule_payload(self),
+        superseded: superseded,
+        created: created
+      })
+    end
+
     # Create and save an execution, then enqueue it to Beanstalkd.
     #
     # The execution is enqueued immediately with appropriate delay - Beanstalkd's
@@ -355,13 +581,17 @@ module Postburner
     # Instruments with ActiveSupport::Notifications:
     # - create.schedule_execution.postburner: When execution is created
     #
-    # @param after [Time, ScheduleExecution, nil] Calculate after this time/execution
+    # @param after [Time, ScheduleExecution, nil] Calculate the slot as the next
+    #   grid point after this time/execution (legacy bootstrap path).
+    # @param at [Time, nil] Create the execution at this EXACT run_at (used by
+    #   reconcile! / create_next_execution!, which have already computed the precise
+    #   skip-aware grid point). Takes precedence over `after`.
     # @return [ScheduleExecution, nil] The created execution, or nil if no more runs
     #
     # @api private
     #
-    def create_execution!(after: nil)
-      execution = build_execution(after: after)
+    def create_execution!(after: nil, at: nil)
+      execution = build_execution(after: after, at: at)
       return nil if execution.nil?
 
       execution.save!
@@ -383,22 +613,35 @@ module Postburner
 
     # Build an execution record (does not save).
     #
-    # Calculates the next two run times and builds an execution with run_at
-    # and next_run_at set. The execution is not persisted to the database.
+    # Two modes:
+    # - `at:` — create the execution at this EXACT run_at. The next_run_at
+    #   lookahead is the next skip-aware grid point AFTER it, matching what the
+    #   next reconcile/chaining pass will actually create. This is the path used
+    #   by reconcile! and create_next_execution!, which have already computed the
+    #   precise grid point (no `-1s` round-trip, no double grid computation).
+    # - `after:` — legacy path: run_at is the next grid point strictly after the
+    #   given time/execution; next_run_at is the grid point after that.
     #
-    # @param after [Time, ScheduleExecution, nil] Calculate after this time/execution
-    # @return [ScheduleExecution, nil] The built execution, or nil if schedule has no more runs
+    # @param after [Time, ScheduleExecution, nil] Calculate the slot after this
+    # @param at [Time, nil] Build at this exact run_at (takes precedence)
+    # @return [ScheduleExecution, nil] The built execution, or nil if no more runs
     #
     # @api private
     #
-    def build_execution(after: nil)
-      after_time = after.is_a?(ScheduleExecution) ? after.run_at : after
-      times = next_run_at_times(after: after_time, count: 2)
+    def build_execution(after: nil, at: nil)
+      if at
+        run_at = at
+        # Lookahead matches the next slot the scheduler would create next time.
+        next_run_at = next_grid_point_skipping_cancelled(after: at)
+      else
+        after_time = after.is_a?(ScheduleExecution) ? after.run_at : after
+        times = next_run_at_times(after: after_time, count: 2)
 
-      return nil if times.empty?
+        return nil if times.empty?
 
-      run_at = times[0]
-      next_run_at = times[1] # May be nil if count is 1 or no more runs
+        run_at = times[0]
+        next_run_at = times[1] # May be nil if count is 1 or no more runs
+      end
 
       executions.build(
         run_at: run_at,