chrono_forge 0.9.1 → 0.11.0

data/lib/chrono_forge/executor.rb

@@ -14,46 +14,105 @@ module ChronoForge
 
     class InvalidStepName < NotExecutableError; end
 
+    # spawn/spawn_each called outside a branch block. NotExecutableError so it
+    # propagates (fail-fast on a programming error) rather than being retried.
+    class NotInBranchError < NotExecutableError; end
+
+    # A branch was opened but neither merged via merge_branches nor declared
+    # automerge: true. Raised at the completion gate. Fail-fast (not retried).
+    class UnmergedBranchError < NotExecutableError; end
+
+    # merge_branches given a name that was never opened as a branch this pass.
+    # NotExecutableError so it propagates (fail-fast) instead of being retried.
+    class UnknownBranchError < NotExecutableError; end
+
     # "$" separates the segments of a step name (e.g. "durably_repeat$name$ts").
     # User-supplied names/methods must not contain it.
     STEP_NAME_DELIMITER = "$"
 
+    # Keyword args ChronoForge threads through job args internally. Users must
+    # not pass these to perform_now/perform_later; the framework injects them
+    # via `.set(...)` continuations, whose ConfiguredJob proxy bypasses the
+    # class-level guard in `prepended` below.
+    RESERVED_KWARGS = %i[attempt retry_counts retry_workflow].freeze
+
     include Methods
 
     # Add class methods
     def self.prepended(base)
+      # Class-wide default retry policy, inherited by subclasses. Set via the
+      # `retry_policy` DSL below; nil means "use the per-site built-in default".
+      base.class_attribute :default_retry_policy, instance_accessor: false, default: nil
+
       class << base
-        # Enforce expected signature for perform_now with key as first arg and keywords after
-        def perform_now(key, **kwargs)
-          if !key.is_a?(String)
-            raise ArgumentError, "Workflow key must be a string as the first argument"
-          end
-          super
+        # Public enqueue contract: exactly one positional (`key`) plus keywords.
+        # Reserved internal kwargs (RESERVED_KWARGS) are rejected here; the
+        # framework injects them only via `.set(...)` continuations, whose
+        # ActiveJob ConfiguredJob proxy bypasses these class-level overrides.
+        def perform_now(key, *extra, **kwargs)
+          __validate_enqueue!(key, extra, kwargs)
+          super(key, **kwargs)
         end
 
-        # Enforce expected signature for perform_later with key as first arg and keywords after
-        def perform_later(key, **kwargs)
-          if !key.is_a?(String)
-            raise ArgumentError, "Workflow key must be a string as the first argument"
-          end
-          super
+        def perform_later(key, *extra, **kwargs)
+          __validate_enqueue!(key, extra, kwargs)
+          super(key, **kwargs)
+        end
+
+        # Re-run a failed/stalled workflow. Routes through `.set(...)` so the
+        # reserved `retry_workflow: true` flag reaches the instance perform
+        # without tripping the public guard above.
+        def retry_now(key, **kwargs)
+          __validate_enqueue!(key, [], kwargs)
+          set.perform_now(key, retry_workflow: true, **kwargs)
         end
 
-        # Add retry_now class method that calls perform_now with retry_workflow: true
-        def retry_now(key, **)
-          perform_now(key, retry_workflow: true, **)
+        def retry_later(key, **kwargs)
+          __validate_enqueue!(key, [], kwargs)
+          set.perform_later(key, retry_workflow: true, **kwargs)
         end
 
-        # Add retry_later class method that calls perform_later with retry_workflow: true
-        def retry_later(key, **)
-          perform_later(key, retry_workflow: true, **)
+        # Class-level DSL to set this workflow's default retry policy. Applies to
+        # workflow-level retries and to steps without a per-call override.
+        # Positional RetryPolicy objects build a composite (per-error budgets);
+        # keyword options build a single RetryPolicy. The two forms are mutually
+        # exclusive.
+        def retry_policy(*policies, **opts)
+          if policies.any? && opts.any?
+            raise ArgumentError, "retry_policy takes either positional policies or keyword options, not both"
+          end
+
+          self.default_retry_policy =
+            policies.any? ? RetryPolicy.compose(*policies) : RetryPolicy.new(**opts)
+        end
+
+        private
+
+        def __validate_enqueue!(key, extra, kwargs)
+          unless key.is_a?(String)
+            raise ArgumentError, "Workflow key must be a string as the first argument"
+          end
+          unless extra.empty?
+            raise ArgumentError,
+              "ChronoForge workflows accept only `key` positionally; pass " \
+              "everything else as keywords (got #{extra.size} extra positional arg(s))"
+          end
+          reserved = kwargs.keys & RESERVED_KWARGS
+          if reserved.any?
+            raise ArgumentError,
+              "#{reserved.join(", ")} #{reserved.one? ? "is a reserved" : "are reserved"} " \
+              "ChronoForge #{reserved.one? ? "keyword" : "keywords"} and cannot be passed to perform_now/perform_later"
+          end
         end
       end
     end
 
-    def perform(key, attempt: 0, retry_workflow: false, options: {}, **kwargs)
-      # Prevent excessive retries
-      if attempt >= self.class::RetryStrategy.max_attempts
+    def perform(key, attempt: 0, retry_counts: {}, retry_workflow: false, options: {}, **kwargs)
+      # Safety net: prevent re-running a workflow whose attempts are exhausted
+      # (e.g. a stale job left in the queue). The normal exhaustion path fails the
+      # workflow from the rescue below before this is ever reached.
+      policy = workflow_retry_policy
+      if policy.max_attempts && attempt >= policy.max_attempts
         Rails.logger.error { "ChronoForge:#{self.class} max attempts reached for job workflow(#{key})" }
         return
       end
@@ -101,16 +160,39 @@ module ChronoForge
         Rails.logger.error { "ChronoForge:#{self.class}(#{key}) workflow execution failed" }
         error_log = self.class::ExecutionTracker.track_error(workflow, e, attempt: attempt)
 
-        # Retry if applicable
-        if should_retry?(e, attempt)
-          self.class::RetryStrategy.schedule_retry(workflow, attempt: attempt)
+        # Retry if applicable. `attempt` is a 0-based index, so the count of
+        # attempts made so far (including this one) is attempt + 1. For a
+        # composite policy the per-error budget lives in `retry_counts` (keyed by
+        # the matched policy's budget_key) and rides along the job args, mirroring
+        # how `attempt` is threaded — there is no execution log at this level.
+        attempts_made = attempt + 1
+        backoff = policy.retry_backoff(e, attempts: attempts_made) do |policy_key|
+          retry_counts[policy_key] = retry_counts[policy_key].to_i + 1
+          retry_counts[policy_key]
+        end
+        if backoff
+          enqueue_continuation(wait: backoff, attempt: attempts_made, retry_counts: retry_counts)
         else
           fail_workflow! error_log
         end
       ensure
         if lock_acquired # Only release lock if we acquired it
-          context.save!
-          self.class::LockStrategy.release_lock(job_id, workflow)
+          # Release the lock and publish the continuation even if context.save!
+          # raises — otherwise a transient save failure would leave the lock held
+          # (until it goes stale) AND drop the continuation, stranding the workflow
+          # with nothing scheduled to resume it. On a save failure the continuation
+          # resumes from the last persisted context, which is exactly crash
+          # semantics (durable steps replay).
+          begin
+            context.save!
+          ensure
+            self.class::LockStrategy.release_lock(job_id, workflow)
+            # Publish the continuation only now — after the lock is released — so a
+            # zero-delay, same-key continuation can't lose the acquire race against
+            # this still-locked job. If release_lock raised (this job overran and
+            # lost the lock), we never reach here and another job owns continuation.
+            flush_continuation!
+          end
         end
       end
     end
@@ -148,11 +230,84 @@ module ChronoForge
     # which accumulate unbounded repetition logs: we touch only the rows we need,
     # never the whole set. create_or_find_by! is used only on a miss, keeping
     # creation safe if a lock takeover ever lets two executors race.
+    #
+    # Completed steps are short-circuited up front from a single bulk read (see
+    # #completed_step_cache) so that replaying N already-done steps costs one
+    # query for the whole batch rather than one SELECT each — without that, a
+    # workflow with hundreds of steps pays hundreds of SELECTs on every resume.
+    # The cached value is a readonly, unsaved stand-in: completed steps are only
+    # ever read (.completed? and metadata["result"]), never written, so it needs
+    # no database row.
     def find_or_create_execution_log!(step_name, &)
+      if completed_step_cache.key?(step_name)
+        return ExecutionLog.new(
+          workflow: @workflow, step_name: step_name, state: :completed,
+          metadata: completed_step_cache[step_name]
+        ).tap(&:readonly!)
+      end
+
       ExecutionLog.find_by(workflow: @workflow, step_name: step_name) ||
         ExecutionLog.create_or_find_by!(workflow: @workflow, step_name: step_name, &)
     end
 
+    # Record a step that completes synchronously within this pass as a single
+    # INSERT already in its terminal :completed state — there is no
+    # started→completed UPDATE chasing the INSERT (one statement, not two). Use
+    # this for steps with no deferral point between create and completion
+    # (workflow completion/failure markers and similar); deferring steps (waits,
+    # branch coordination) must stay :started across resumes and use
+    # find_or_create_execution_log! instead.
+    #
+    # Idempotent: an already-existing row (a resume after a partial pass, or a
+    # create race) is flipped to :completed instead of duplicated. The block runs
+    # only on create, letting callers attach metadata to the new row.
+    def create_completed_execution_log!(step_name)
+      now = Time.current
+      log = find_or_create_execution_log!(step_name) do |l|
+        l.attempts = 1
+        l.started_at = now
+        l.last_executed_at = now
+        l.completed_at = now
+        l.state = :completed
+        yield l if block_given?
+      end
+
+      unless log.completed?
+        log.update!(
+          attempts: log.attempts + 1,
+          last_executed_at: now,
+          completed_at: now,
+          state: :completed
+        )
+      end
+
+      log
+    end
+
+    # One bulk read of this workflow's completed steps, mapping step_name to its
+    # metadata, memoized for the duration of a single replay pass.
+    #
+    # Only completed rows are loaded: they are the ones replayed steps short-
+    # circuit on, and once completed a step never changes, so the snapshot stays
+    # valid for the whole pass. Plucking (step_name, metadata) avoids
+    # instantiating AR objects and keeps the read portable — Rails type-casts the
+    # JSON metadata column to a Hash on SQLite, PostgreSQL and MySQL alike, with
+    # no database-specific JSON extraction.
+    #
+    # durably_repeat repetition logs (durably_repeat$<name>$<timestamp>) are
+    # deliberately excluded: they accumulate without bound yet are never replayed
+    # (durably_repeat only ever looks up its coordination log plus the single
+    # current repetition), so pulling them into memory would be all cost and no
+    # benefit. Their coordination log (durably_repeat$<name>, only two segments)
+    # is not matched by the pattern and is still cached.
+    def completed_step_cache
+      @completed_step_cache ||= ExecutionLog
+        .where(workflow: @workflow, state: ExecutionLog.states[:completed])
+        .where.not("step_name LIKE ?", "durably_repeat#{STEP_NAME_DELIMITER}%#{STEP_NAME_DELIMITER}%")
+        .pluck(:step_name, :metadata)
+        .to_h
+    end
+
     # Guards the user-supplied portion of a step name (a custom name, method, or
     # condition). The "$" separator is reserved for the framework's own segment
     # structure, so a user value containing it would make step names ambiguous
@@ -164,8 +319,66 @@ module ChronoForge
         "ChronoForge step name may not contain '#{STEP_NAME_DELIMITER}' (reserved separator): #{segment.inspect}"
     end
 
-    def should_retry?(error, attempt_count)
-      attempt_count < 3
+    # Retry policy for workflow-level (uncaught) errors: the class default if one
+    # was declared, else the workflow built-in (10 attempts, up to ~8.5 min).
+    # Each retry replays the whole workflow from the top.
+    def workflow_retry_policy
+      self.class.default_retry_policy || RetryPolicy.workflow_default
+    end
+
+    # Retry policy for a durable step: an explicit per-call override, else the
+    # class default, else the step built-in (short, snappy fast-fail).
+    def step_retry_policy(override)
+      coerce_policy(override) || self.class.default_retry_policy || RetryPolicy.step_default
+    end
+
+    # Retry policy for a wait_until condition error. Deliberately does NOT inherit
+    # the class default, so a class-wide "retry everything" can't silently turn
+    # condition-evaluation bugs into retried errors. Built-in retries nothing.
+    def wait_retry_policy(override)
+      coerce_policy(override) || RetryPolicy.wait_default
+    end
+
+    # Normalize a retry-policy value: an Array becomes a composite; a RetryPolicy
+    # or CompositeRetryPolicy passes through; nil stays nil.
+    def coerce_policy(value)
+      value.is_a?(Array) ? RetryPolicy.compose(*value) : value
+    end
+
+    # JSON metadata key holding the per-error attempt counts of a composite
+    # policy, keyed by the matched policy's declared errors (RetryPolicy#budget_key).
+    RETRY_COUNTS_KEY = "retry_counts"
+
+    # Increment the matched policy's slot in the log's retry-count map and return
+    # the new count. Reassigns `metadata` so the JSON column is marked dirty.
+    def bump_retry_count!(log, policy_key)
+      meta = log.metadata || {}
+      counts = meta[RETRY_COUNTS_KEY] || {}
+      counts[policy_key] = counts[policy_key].to_i + 1
+      meta[RETRY_COUNTS_KEY] = counts
+      log.update!(metadata: meta)
+      counts[policy_key]
+    end
+
+    # Record the continuation this job intends to enqueue. It is NOT published
+    # here: publishing while the lock is still held lets another worker claim it
+    # and lose the lock-acquisition race. The executor flushes it in `ensure`,
+    # after release_lock (see #flush_continuation!). At most one continuation is
+    # recorded per job run (every primitive records one then halts, or falls
+    # through the workflow-retry rescue).
+    def enqueue_continuation(wait:, **kwargs)
+      @continuation = {wait: wait, kwargs: kwargs}
+    end
+
+    # Publish the recorded continuation, if any. Called from `ensure` only after
+    # the lock row has been updated to released, so even a zero-delay continuation
+    # finds the lock free.
+    def flush_continuation!
+      return unless @continuation
+
+      self.class
+        .set(wait: @continuation[:wait])
+        .perform_later(@workflow.key, **@continuation[:kwargs])
     end
 
     def halt_execution!

data/lib/chrono_forge/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ChronoForge
-  VERSION = "0.9.1"
+  VERSION = "0.11.0"
 end

data/lib/chrono_forge/workflow.rb

@@ -12,6 +12,7 @@
 #  kwargs       :json             not null
 #  options      :json             not null
 #  locked_at    :datetime
+#  parent_execution_log_id :integer
 #  started_at   :datetime
 #  state        :integer          default("idle"), not null
 #  created_at   :datetime         not null
@@ -19,7 +20,10 @@
 #
 # Indexes
 #
-#  index_chrono_forge_workflows_on_key  (key) UNIQUE
+#  index_chrono_forge_workflows_on_key                         (key)
+#  index_chrono_forge_workflows_on_job_class_and_key           (job_class,key) UNIQUE
+#  index_chrono_forge_workflows_on_parent_execution_log_and_st (parent_execution_log_id,state)
+#  index_chrono_forge_workflows_on_state_and_completed_at      (state,completed_at)
 #
 module ChronoForge
   class Workflow < ApplicationRecord()
@@ -28,6 +32,11 @@ module ChronoForge
     has_many :execution_logs, dependent: :destroy
     has_many :error_logs, dependent: :destroy
 
+    belongs_to :parent_execution_log,
+      class_name: "ChronoForge::ExecutionLog",
+      inverse_of: :spawned_workflows,
+      optional: true
+
     enum :state, %i[
       idle
       running

data/lib/chrono_forge.rb

@@ -13,4 +13,12 @@ module ChronoForge
   class Error < StandardError; end
 
   def self.ApplicationRecord = defined?(::ApplicationRecord) ? ::ApplicationRecord : ActiveRecord::Base
+
+  # Engine configuration (see ChronoForge::Configuration).
+  #   ChronoForge.configure { |c| c.branch_merge_queue = :chrono_forge_pollers }
+  def self.config = @config ||= Configuration.new
+
+  def self.configure = yield(config)
+
+  def self.reset_configuration! = @config = Configuration.new
 end

data/lib/generators/chrono_forge/migration_actions.rb

@@ -18,6 +18,7 @@ module ChronoForge
         install_chrono_forge
         add_chrono_forge_workflow_state_index
         add_chrono_forge_error_log_step_context
+        add_chrono_forge_parent_execution_log
       ].freeze
 
       def copy_chrono_forge_migrations

data/lib/generators/chrono_forge/templates/add_chrono_forge_parent_execution_log.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Adds chrono_forge_workflows.parent_execution_log_id: the execution log that
+# spawned a workflow (for branches, the branch$<name> log). Deliberately generic
+# so any future step that spawns sub-workflows can reuse it. The composite
+# [parent_execution_log_id, state] index makes the merge completion probe and the
+# dropped-job re-kick index-only at hundreds of thousands of children.
+#
+# Shipped standalone (matching add_chrono_forge_workflow_state_index) so existing
+# installs pick it up via `rails generate chrono_forge:upgrade`.
+class AddChronoForgeParentExecutionLog < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+
+  def change
+    add_column :chrono_forge_workflows, :parent_execution_log_id, parent_log_fk_type,
+      null: true, if_not_exists: true
+
+    add_index :chrono_forge_workflows, %i[parent_execution_log_id state],
+      if_not_exists: true, **chrono_forge_index_algorithm
+  end
+
+  private
+
+  # Match the type of chrono_forge_workflows.id so the FK lines up on both bigint
+  # and uuid installs.
+  def parent_log_fk_type
+    id_col = connection.columns(:chrono_forge_workflows).find { |c| c.name == "id" }
+    (id_col&.type == :uuid) ? :uuid : :bigint
+  end
+
+  def chrono_forge_index_algorithm
+    if connection.adapter_name.to_s.downcase.include?("postgresql")
+      {algorithm: :concurrently}
+    else
+      {}
+    end
+  end
+end

data/lib/tasks/release.rake

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+# Release flow (chrono_forge monorepo: core + dashboard)
+# ------------------------------------------------------
+# Publishing happens from a laptop. CI does NOT push to any registry — it only
+# cuts the GitHub Release (notes + the built gem) when the tag lands.
+#
+#   1. rake release:core:prepare           # auto-computes next version (git-cliff)
+#      rake release:core:prepare[0.11.0]   # ...or pass one explicitly
+#   2. git diff                            # review the bump + changelog (nothing committed yet)
+#   3. rake release:core:publish           # commit, build + push gem, then tag + push → CI cuts the Release
+#
+# Same tasks under release:dashboard:*. Release `core` BEFORE `dashboard` —
+# the dashboard depends on core, so bump its `chrono_forge` floor first if needed.
+#
+# prepare leaves the bump + changelog UNCOMMITTED so you can review the diff
+# first; publish commits them, then publishes. publish is idempotent + resumable:
+# it skips a gem already live and only tags if the tag is missing, so a partial
+# failure can just be re-run.
+
+RELEASE_CLIFF_CONFIG = "cliff.toml"
+
+# Per-gem config. tag_pattern + scope mirror what each CHANGELOG should reflect:
+# core = everything except the dashboard subtree, dashboard = only that subtree.
+RELEASE_GEMS = {
+  "core" => {
+    name: "chrono_forge",
+    version_file: "lib/chrono_forge/version.rb",
+    changelog: "CHANGELOG.md",
+    gemspec: "chrono_forge.gemspec",
+    build_dir: ".",
+    tag_prefix: "v",
+    tag_pattern: "^v[0-9]",
+    scope: ["--exclude-path", "chrono_forge-dashboard/**"],
+    extra_files: []
+  },
+  "dashboard" => {
+    name: "chrono_forge-dashboard",
+    version_file: "chrono_forge-dashboard/lib/chrono_forge/dashboard/version.rb",
+    changelog: "chrono_forge-dashboard/CHANGELOG.md",
+    gemspec: "chrono_forge-dashboard.gemspec",
+    build_dir: "chrono_forge-dashboard",
+    tag_prefix: "chrono_forge-dashboard-v",
+    tag_pattern: "^chrono_forge-dashboard-v[0-9]",
+    scope: ["--include-path", "chrono_forge-dashboard/**"],
+    # The dashboard ships a compiled stylesheet — recompile it so the tagged
+    # tree (and the gem) never ship CSS that lags the source/views.
+    assets: -> {
+      Dir.chdir("chrono_forge-dashboard") do
+        system("bundle", "exec", "rake", "tailwind:build") || abort("tailwind:build failed")
+      end
+    },
+    extra_files: ["chrono_forge-dashboard/app/assets/chrono_forge/dashboard/dashboard.css"]
+  }
+}
+
+namespace :release do
+  # --- helpers --------------------------------------------------------------
+
+  def git_cliff?
+    system("which git-cliff > /dev/null 2>&1")
+  end
+
+  def release_current_version(cfg)
+    File.read(cfg[:version_file])[/VERSION = "([\d.]+)"/, 1] ||
+      abort("Could not read VERSION from #{cfg[:version_file]}")
+  end
+
+  def release_cliff_cmd(cfg, *extra)
+    ["git-cliff", "--config", RELEASE_CLIFF_CONFIG, "--tag-pattern", cfg[:tag_pattern], *cfg[:scope], *extra]
+  end
+
+  # Capture git-cliff stdout, discarding the stderr update-check chatter.
+  def release_capture(cmd)
+    IO.popen(cmd, err: File::NULL, &:read)
+  end
+
+  # Next version per conventional commits. git-cliff owns the semver math
+  # (including the pre-1.0 rules under [bump] in cliff.toml). Returns it
+  # without the gem's tag prefix.
+  def release_next_version(cfg)
+    abort "git-cliff not found. Install with: brew install git-cliff" unless git_cliff?
+    bumped = release_capture(release_cliff_cmd(cfg, "--bumped-version")).strip
+    abort "git-cliff could not compute a version (no conventional commits since the last #{cfg[:name]} tag?)" if bumped.empty?
+    bumped.delete_prefix(cfg[:tag_prefix])
+  end
+
+  def release_gem_published?(cfg, version)
+    out = `gem list --remote --exact --all #{cfg[:name]} 2>/dev/null`
+    out.include?("#{version},") || out.include?("#{version})") || out.include?(" #{version} ")
+  end
+
+  # Inject ONLY this version's section above the latest entry. A full -o regen
+  # would misattribute past releases because path-filtering confuses cliff's
+  # historical tag boundaries; existing entries are preserved verbatim.
+  def release_prepend_changelog(path, section)
+    body = File.read(path)
+    block = "#{section.strip}\n\n"
+    updated = (body =~ /^## \[/) ? body.sub(/^## \[/, "#{block}## [") : "#{body.rstrip}\n\n#{block}"
+    File.write(path, updated)
+  end
+
+  # --- per-gem tasks --------------------------------------------------------
+
+  RELEASE_GEMS.each do |key, cfg|
+    namespace key do
+      desc "Show #{cfg[:name]}'s next version computed from conventional commits"
+      task :version do
+        puts "#{cfg[:name]} current: #{release_current_version(cfg)}"
+        puts "#{cfg[:name]} next:    #{release_next_version(cfg)}"
+      end
+
+      desc "Prepare a #{cfg[:name]} release commit (bump + changelog + assets). Version optional; git-cliff computes it."
+      task :prepare, [:version] do |_t, args|
+        version = args[:version] || release_next_version(cfg)
+        abort "Error: version must be in format X.Y.Z (got #{version.inspect})" unless version.match?(/^\d+\.\d+\.\d+$/)
+        abort "Error: working tree is dirty. Commit or stash first." unless `git status --porcelain`.strip.empty?
+        abort "Error: not on main." unless `git rev-parse --abbrev-ref HEAD`.strip == "main"
+
+        system("git fetch -q origin")
+        abort "Error: main is not in sync with origin/main." unless `git rev-parse HEAD`.strip == `git rev-parse origin/main`.strip
+
+        tag = "#{cfg[:tag_prefix]}#{version}"
+        abort "Error: tag #{tag} already exists." if system("git rev-parse #{tag} >/dev/null 2>&1")
+
+        puts "Preparing #{cfg[:name]} #{version} (tag #{tag})..."
+
+        # Bump version.
+        content = File.read(cfg[:version_file])
+        File.write(cfg[:version_file], content.gsub(/VERSION = "[\d.]+"/, %(VERSION = "#{version}")))
+        puts "✓ #{cfg[:version_file]}"
+
+        # Compile assets (dashboard CSS), if any.
+        cfg[:assets]&.call
+
+        # Changelog — same config CI uses for the notes, so they agree.
+        section = release_capture(release_cliff_cmd(cfg, "--tag", tag, "--unreleased", "--strip", "all"))
+        abort "git-cliff found no entries since the last #{cfg[:name]} tag — nothing to release." if section.strip.empty?
+        release_prepend_changelog(cfg[:changelog], section)
+        puts "✓ #{cfg[:changelog]}"
+
+        # Leave everything uncommitted so the bump + changelog can be reviewed
+        # before anything is committed or published. publish makes the commit.
+        files = [cfg[:version_file], cfg[:changelog], *cfg[:extra_files]]
+
+        puts "\n✓ Prepared #{cfg[:name]} #{version} — nothing committed yet."
+        puts "Next:"
+        puts "  git diff -- #{files.join(" ")}"
+        puts "  rake release:#{key}:publish   # commit, build + push gem, then tag + push"
+        puts "  (abort with: git checkout -- #{files.join(" ")})"
+      end
+
+      desc "Publish #{cfg[:name]} (build + push gem, then tag + push). Idempotent + resumable."
+      task :publish do
+        version = release_current_version(cfg)
+        tag = "#{cfg[:tag_prefix]}#{version}"
+        files = [cfg[:version_file], cfg[:changelog], *cfg[:extra_files]]
+
+        # Commit the prepared changes (you review the diff between prepare and
+        # here). Resumable: if they're already committed — e.g. a re-run after a
+        # partial failure — skip straight to publishing.
+        if `git status --porcelain -- #{files.join(" ")}`.strip.empty?
+          unless `git log -1 --format=%s`.strip == "chore(release): #{cfg[:name]} #{version}"
+            abort "Nothing prepared — run rake release:#{key}:prepare first."
+          end
+        else
+          system("git", "add", *files) || abort("git add failed")
+          system("git", "commit", "-m", "chore(release): #{cfg[:name]} #{version}") || abort("git commit failed")
+          puts "✓ Committed #{cfg[:name]} #{version}"
+        end
+
+        if release_gem_published?(cfg, version)
+          puts "• #{cfg[:name]} #{version} already on RubyGems — skipping"
+        else
+          puts "Building + pushing gem..."
+          Dir.chdir(cfg[:build_dir]) do
+            system("gem build #{cfg[:gemspec]}") || abort("Gem build failed")
+            gem_file = "#{cfg[:name]}-#{version}.gem"
+            system("gem push #{gem_file}") || abort("Gem push failed")
+            File.delete(gem_file) if File.exist?(gem_file)
+          end
+          puts "✓ Published #{cfg[:name]} #{version} to RubyGems"
+        end
+
+        # Tag + push last, so CI cuts the Release only once the gem is live.
+        branch = `git branch --show-current`.strip
+        if system("git rev-parse #{tag} >/dev/null 2>&1")
+          puts "• tag #{tag} already exists — skipping tag"
+        else
+          system("git", "tag", tag) || abort("git tag failed")
+        end
+        system("git", "push", "origin", branch) || abort("git push branch failed")
+        system("git", "push", "origin", tag) || abort("git push tag failed")
+
+        puts "\n✓ Released #{tag}. GitHub Actions will cut the Release from the tag."
+        if key == "core"
+          puts "  Next: bump the dashboard's chrono_forge floor if it should require #{version}, then release:dashboard:*"
+        end
+      end
+    end
+  end
+end
+
+# Neutralize the dangerous bare `rake release` that bundler/gem_tasks defines
+# (it would tag + gem push directly). Point people at the real flow instead.
+if Rake::Task.task_defined?("release")
+  Rake::Task["release"].clear
+  desc "Disabled — use release:core:* or release:dashboard:* (see lib/tasks/release.rake)"
+  task :release do
+    warn "Use `rake release:core:prepare` then `rake release:core:publish` (or :dashboard). See lib/tasks/release.rake."
+  end
+end