belay 0.1.0

data/lib/belay/step.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Belay
+  class Step < ApplicationRecord
+    self.table_name = "belay_steps"
+
+    # Explicit class_name: this gem has no Zeitwerk/app-autoloading, so association
+    # class lookup can't rely on namespace inference the way it would inside a
+    # conventionally-autoloaded Rails engine. Explicit optional: false too: Rails only
+    # requires belongs_to associations by default when the host app's load_defaults is
+    # 7.0+. A library shouldn't depend on that config to get a friendly validation error
+    # instead of a raw DB NotNullViolation.
+    belongs_to :run, class_name: "Belay::Run", optional: false
+
+    # has_one, not has_many: belay_approvals.step_id is unique at the DB level -
+    # at most one approval per gate step (see its migration's own comment on why,
+    # and the forward constraint that assumes).
+    has_one :approval, class_name: "Belay::Approval"
+
+    enum :kind, {
+      llm_call: "llm_call",
+      tool_call: "tool_call",
+      decision: "decision",
+      gate: "gate"
+    }
+
+    enum :status, {
+      started: "started",
+      succeeded: "succeeded",
+      failed: "failed",
+      skipped: "skipped",
+      needs_review: "needs_review",
+      # Only a gate ever settles here: when: evaluated true, and this step is
+      # paused waiting for a human's Run#approve!/reject!. Distinct from
+      # "started" (crashed-or-in-flight, resumed via the
+      # idempotent?/needs_review policy) and from "needs_review" (a different
+      # kind of human intervention, for a non-idempotent step orphaned by a
+      # crash) - this one is a clean, intentional pause, not a recovery path.
+      awaiting_approval: "awaiting_approval"
+    }
+
+    validates :position, presence: true
+    validates :name, presence: true
+    validates :kind, presence: true
+    validates :idempotency_key, presence: true
+
+    # status has a DB default ("started"), but the enum writer accepts nil as a valid
+    # "blank" assignment (no ArgumentError) - without this, an explicit status: nil
+    # would skip the default and hit a raw NotNullViolation instead of RecordInvalid.
+    validates :status, presence: true
+
+    # No guarded transitions here, unlike Run: the executor (Phase 1e) owns the
+    # started -> succeeded/failed/needs_review policy, including retry rules that
+    # depend on an idempotent: declaration this model doesn't have. Adding bang
+    # methods here now would mean rebuilding them once that policy exists.
+  end
+end

data/lib/belay/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Belay
+  VERSION = "0.1.0"
+end

data/lib/belay/workflow.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Belay
+  # Base class for workflow definitions (see README's Target API). .input/.step are pure
+  # declaration; .start (below) is where a Run actually gets created and executed.
+  class Workflow
+    StepDefinition = Struct.new(:name, :kind, :options, :block, keyword_init: true)
+
+    class << self
+      def input(*names)
+        names.each do |name|
+          name = name.to_sym
+          raise ArgumentError, "input :#{name} is already declared on #{self}" if raw_inputs.include?(name)
+
+          raw_inputs << name
+        end
+      end
+
+      # Returns a frozen copy: mutating the result (push, clear, reassign) can never
+      # corrupt what .input actually declared, and can't bypass its duplicate check.
+      def inputs
+        raw_inputs.dup.freeze
+      end
+
+      # kind isn't validated against Belay::Step's kind enum here - that's the AR/
+      # persistence layer's job (Step#kind), not this thin declaration layer's. nil
+      # (the default, since no Target API example passes it) hashes consistently with
+      # itself in workflow_version; inferring a real kind is executor work (Phase 1e+).
+      #
+      # kind: is reserved by this gem the same way the belay_steps.kind column is - a
+      # host app passing an unrelated option literally named kind: would have it
+      # silently captured here instead of landing in options. Accepted, not guarded:
+      # the name is already Belay-specific throughout this project, not a generic term
+      # a workflow author would likely reach for on their own.
+      def step(name, kind: nil, **options, &block)
+        raise ArgumentError, "step :#{name} needs a block" unless block
+
+        validate_step_kind!(name, kind)
+        name = reserve_name!(name)
+
+        raw_steps << StepDefinition.new(
+          name: name, kind: kind&.to_sym, options: options.dup.freeze, block: block
+        ).freeze
+      end
+
+      # DESIGN_DECISIONS #7: "Gates are steps" - a gate lives in the same ordered
+      # raw_steps list as step (so Executor's single each_with_index walk sees it in
+      # position, and workflow_version's fingerprint already covers it via
+      # steps.map { [name, kind] }, with no special-casing needed there). kind: is
+      # always :gate here, not an option the caller can override - unlike step,
+      # where kind: is optional metadata, a gate's kind is what makes it one.
+      #
+      # when: is accepted through **options rather than declared as its own `when:`
+      # keyword parameter. Ruby accepts when: as a keyword argument NAME just fine
+      # (def gate(name, when:) parses), but referencing it afterward as a bare local
+      # variable does not - `when` alone is reserved for case/when, a SyntaxError
+      # distinct from the argument's own definition. Reading it back out of options
+      # (options[:when]) sidesteps that entirely rather than requiring
+      # binding.local_variable_get(:when) everywhere it's used.
+      #
+      # No block: a gate has nothing to execute - when: decides skip (false) or wait
+      # for a human (true). What the executor actually does with kind: :gate is the
+      # next commit's job; this one only declares it.
+      def gate(name, **options)
+        raise ArgumentError, "gate :#{name} must not pass kind: - a gate's kind is always :gate" if options.key?(:kind)
+
+        condition = options[:when]
+        validate_gate_when!(name, condition)
+        name = reserve_name!(name)
+
+        raw_steps << StepDefinition.new(
+          name: name, kind: :gate, options: options.dup.freeze, block: nil
+        ).freeze
+      end
+
+      # Frozen copy, same reasoning as #inputs. Each StepDefinition is frozen too, so a
+      # caller can't reach back in and change a step's block or options after the fact.
+      def steps
+        raw_steps.dup.freeze
+      end
+
+      # Hashes structure, not block bodies: Ruby source can't be hashed reliably (a
+      # renamed local variable or a reformatted block changes nothing about what the
+      # step actually does, but would change its source text). Covers declared inputs,
+      # and each step's name and kind in order - deliberately not step options yet
+      # (idempotent:/retries: aren't interpreted anywhere yet either; see .step's
+      # comment). No explicit position field: Array#inspect is already order-sensitive
+      # on its own, so swapping two steps changes the fingerprint without needing one.
+      def workflow_version
+        fingerprint = [inputs, steps.map { |step| [step.name, step.kind] }]
+        Digest::SHA256.hexdigest(fingerprint.inspect)
+      end
+
+      # README's Target API: InvoiceWorkflow.start(invoice_id: 42, idempotency_key: "inv-42").
+      # idempotency_key: dedups at the RUN level (distinct from a step's own
+      # step_idempotency_key): calling .start twice with the same key returns the same
+      # Run rather than starting a second one, racing on belay_runs' own unique index
+      # on idempotency_key rather than a check-then-create in Ruby, which two
+      # concurrent callers could both pass.
+      #
+      # The dedup lookup runs before input validation, not after: a repeat call with
+      # the same key is asking "what happened to that run," and the input was already
+      # validated when the run was first created - a caller-side bug on a retry
+      # (stale/missing input) shouldn't turn a successful repeat lookup into an
+      # ArgumentError for a run that already exists and needs no further input at all.
+      #
+      # Only the run THIS call actually creates gets executed. A found-existing run -
+      # whether found outright or found after losing the create race - is returned
+      # without calling the executor on it: this gem has no lease mechanism yet
+      # (Phase 1f) to make running the same Executor concurrently from two places
+      # safe, so piling onto a run some OTHER caller may already be executing isn't
+      # attempted here.
+      def start(idempotency_key:, **input)
+        existing = Run.find_by(idempotency_key: idempotency_key)
+        return check_same_workflow!(existing) if existing
+
+        validate_input!(input)
+        run, newly_created = find_or_create_run(idempotency_key, input)
+        Executor.new(run).call if newly_created
+        run
+      end
+
+      private
+
+      def validate_input!(input)
+        missing = inputs - input.keys
+        raise ArgumentError, "#{self}.start is missing required input(s): #{missing.inspect}" unless missing.empty?
+
+        extra = input.keys - inputs
+        return if extra.empty?
+
+        raise ArgumentError,
+              "#{self}.start received undeclared input(s): #{extra.inspect} - declared inputs are #{inputs.inspect}"
+      end
+
+      # The first find_by in #start above already covers the common case; this
+      # second lookup only runs for the race window between that read and this
+      # create - rescue is scoped to just create_run, not the surrounding lookup,
+      # so a RecordNotUnique from somewhere unexpected is never silently caught here.
+      def find_or_create_run(idempotency_key, input)
+        [create_run(idempotency_key, input), true]
+      rescue ActiveRecord::RecordNotUnique
+        [check_same_workflow!(Run.find_by!(idempotency_key: idempotency_key)), false]
+      end
+
+      def create_run(idempotency_key, input)
+        raise Error, "#{self} must be assigned to a constant before .start can use it as a workflow name" if name.nil?
+
+        Run.create!(workflow: name, workflow_version: workflow_version, input: input,
+                    idempotency_key: idempotency_key)
+      end
+
+      # A reused idempotency_key string across two different Workflow subclasses would
+      # otherwise silently return a Run belonging to the wrong workflow entirely.
+      def check_same_workflow!(run)
+        return run if run.workflow == name
+
+        raise Error, "idempotency_key #{run.idempotency_key.inspect} already belongs to a #{run.workflow} run " \
+                     "(belay_runs##{run.id}), not #{self}"
+      end
+
+      # Subclasses never inherit a superclass's declarations: @inputs/@steps are plain
+      # class-level ivars, not class_attribute. `class Child < Base; end` with no further
+      # declarations has Child.steps == [], even if Base declared steps - nothing here
+      # makes that loud, so don't build a "shared base workflow" on this assumption.
+      def raw_inputs
+        @raw_inputs ||= []
+      end
+
+      def raw_steps
+        @raw_steps ||= []
+      end
+
+      def validate_step_kind!(name, kind)
+        return if kind.nil? || kind.is_a?(String) || kind.is_a?(Symbol)
+
+        raise ArgumentError, "step :#{name} kind: must be a String, Symbol, or nil, got #{kind.inspect}"
+      end
+
+      def validate_gate_when!(name, condition)
+        return if condition.respond_to?(:call)
+
+        raise ArgumentError, "gate :#{name} needs when: (something that responds to #call), got #{condition.inspect}"
+      end
+
+      # Shared by step and gate: both end up in the same raw_steps list, walked by
+      # position, so a step and a gate with the same name collide with each other
+      # too, not just within their own kind.
+      def reserve_name!(name)
+        name = name.to_sym
+        return name unless raw_steps.any? { |s| s.name == name }
+
+        raise ArgumentError, "step/gate :#{name} is already declared on #{self}"
+      end
+    end
+  end
+end

data/lib/belay.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Belay
+  # Error must exist before any required file below, since several of them (e.g.
+  # FakeProvider::ScriptExhaustedError) subclass it at load time, not lazily.
+  class Error < StandardError; end
+
+  require_relative "belay/version"
+  require_relative "belay/configuration"
+  require_relative "belay/application_record"
+  require_relative "belay/run"
+  require_relative "belay/step"
+  require_relative "belay/approval"
+  require_relative "belay/cache_entry"
+  require_relative "belay/rule"
+  require_relative "belay/daily_stats"
+  require_relative "belay/workflow"
+  require_relative "belay/context"
+  require_relative "belay/provider_response"
+  require_relative "belay/provider"
+  require_relative "belay/fake_provider"
+  require_relative "belay/anthropic_provider"
+  require_relative "belay/executor"
+  require_relative "belay/resume_run_job"
+  require_relative "belay/janitor_job"
+  require_relative "belay/engine"
+
+  # Raised by Run#start!/pause!/resume!/complete!/fail!/cancel! when the current
+  # status doesn't allow the requested transition.
+  class InvalidTransitionError < Error; end
+
+  class << self
+    def configure
+      yield config
+    end
+
+    # Not thread-safe: a lazy first read from two threads at once could construct
+    # two Configuration objects. Unexercised today (only read at Rails boot); revisit
+    # once workers read config concurrently with a lazy first access (Phase 1f).
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Test-only. Call after mutating config in a spec so it doesn't leak into others.
+    def reset_config!
+      @config = nil
+    end
+  end
+end

data/lib/generators/belay/install/install_generator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record/migration"
+
+module Belay
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      def create_belay_runs_migration
+        migration_template "create_belay_runs.rb.tt", "db/migrate/create_belay_runs.rb"
+      end
+
+      def create_belay_steps_migration
+        migration_template "create_belay_steps.rb.tt", "db/migrate/create_belay_steps.rb"
+      end
+
+      # Last: belay_approvals FKs into both belay_runs and belay_steps, so its
+      # migration needs a timestamp after both of theirs - each migration_template
+      # call gets a fresh, later timestamp than the one before it, same reasoning
+      # that already orders steps after runs above.
+      def create_belay_approvals_migration
+        migration_template "create_belay_approvals.rb.tt", "db/migrate/create_belay_approvals.rb"
+      end
+
+      # No FK into belay_runs/belay_steps - a cache entry isn't tied to any
+      # particular run, so there's no ordering dependency forcing this after
+      # the others.
+      def create_belay_cache_entries_migration
+        migration_template "create_belay_cache_entries.rb.tt", "db/migrate/create_belay_cache_entries.rb"
+      end
+
+      # Last: belay_rules' own migration is what adds the FK from belay_steps.
+      # rule_applied_id into belay_rules (see create_belay_rules.rb.tt's own
+      # comment on why that FK can't live in create_belay_steps.rb.tt instead),
+      # so this table has to exist before that FK statement runs. Not ordered
+      # relative to belay_cache_entries for any dependency reason - just the
+      # one predictable place to look for whichever migration was added most
+      # recently.
+      def create_belay_rules_migration
+        migration_template "create_belay_rules.rb.tt", "db/migrate/create_belay_rules.rb"
+      end
+    end
+  end
+end

data/lib/generators/belay/install/templates/create_belay_approvals.rb.tt

@@ -0,0 +1,43 @@
+class CreateBelayApprovals < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :belay_approvals, id: :uuid do |t|
+      t.uuid :run_id, null: false
+      # A direct FK to the specific gate's belay_steps row, not just a position
+      # column. run_id is kept alongside it too, even though it's already
+      # reachable via step.run_id (one join) - a different kind of
+      # denormalization than belay_steps' idempotency_key (a derived VALUE with
+      # no table to join to at all, kept stable across retries), just the plain
+      # avoid-a-join kind: a dashboard listing pending approvals across runs
+      # shouldn't need to join through steps first.
+      t.uuid :step_id, null: false
+      t.string :status, null: false, default: "pending"
+      t.string :decided_by
+      t.datetime :decided_at
+      # What a human edited before approving, if anything - feat(runs): support
+      # approve! with edited payload, a later commit. Added now, same as
+      # belay_steps' provider/model/token columns sat unused from Phase 1b until
+      # Phase 1g: one migration instead of two for columns whose shape is already
+      # known.
+      t.jsonb :edited_payload
+
+      t.timestamps
+    end
+
+    add_foreign_key :belay_approvals, :belay_runs, column: :run_id
+    add_foreign_key :belay_approvals, :belay_steps, column: :step_id
+
+    add_index :belay_approvals, :run_id
+    # One approval per gate step, enforced at the DB level - but this ASSUMES a
+    # true-condition gate settles into exactly one terminal belay_steps row per
+    # logical occurrence. That's not true yet: today's temporary when: true
+    # handling raises, which reuses the generic step retry loop (same as any
+    # step failure) - a gate declared with retries: N checkpoints N+1 separate
+    # attempt rows before the final raise, per the executor commit's own
+    # review. If the pause-on-gate commit creates an Approval per raise/attempt
+    # instead of exactly once per gate occurrence, THIS constraint breaks it.
+    # Whoever builds that commit: settle a true-condition gate once, not once
+    # per retry attempt, or revisit this index.
+    add_index :belay_approvals, :step_id, unique: true
+    add_index :belay_approvals, :status
+  end
+end

data/lib/generators/belay/install/templates/create_belay_cache_entries.rb.tt

@@ -0,0 +1,27 @@
+class CreateBelayCacheEntries < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :belay_cache_entries, id: :uuid do |t|
+      # SHA256 of [provider class name, model, prompt, schema].inspect - exact,
+      # literal match only (symbol vs string key differences in prompt/schema
+      # are NOT normalized before hashing - a deliberately stricter, simpler
+      # bar than "semantically equivalent"). See Belay::CacheEntry.key_for.
+      #
+      # Named "key", not "cache_key" - ActiveRecord::Base already defines a
+      # #cache_key method of its own (used for fragment-caching/ETag support),
+      # and Rails 7's DangerousAttributeError refuses to let a real column
+      # shadow it. "key" is unambiguous enough inside a model whose own table
+      # is already named belay_cache_entries.
+      t.string :key, null: false
+      t.jsonb :content
+      t.integer :hits, null: false, default: 0
+      # nil means "never expires" - Belay.config.cache_ttl's default is a real
+      # duration, not nil, so this is normally set; nil stays possible for
+      # anyone who explicitly configures cache_ttl = nil.
+      t.datetime :expires_at
+
+      t.timestamps
+    end
+
+    add_index :belay_cache_entries, :key, unique: true
+  end
+end

data/lib/generators/belay/install/templates/create_belay_rules.rb.tt

@@ -0,0 +1,46 @@
+class CreateBelayRules < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :belay_rules, id: :uuid do |t|
+      t.string :workflow, null: false
+      t.string :workflow_version, null: false
+      t.string :gate_name, null: false
+      # SHA256 of [input, outputs, a fingerprint of the when: itself].inspect -
+      # see Belay::Rule.context_key_for for the exact fingerprint and why it's
+      # needed (workflow_version alone doesn't catch an edited when:). The
+      # input/outputs are the SAME ones a gate's when: was evaluated against,
+      # computed once at evaluation time (not re-derived later from a round-
+      # tripped jsonb Hash, which would risk a symbol/string key mismatch
+      # silently breaking the exact match - see Belay::CacheEntry.key_for for
+      # the same reasoning applied there). Deliberately the FULL snapshot, not
+      # just whatever a gate's own when: closure happens to read - a narrower
+      # key could auto-settle a future gate occurrence that looks identical to
+      # the closure but differs in some upstream value nobody declared as
+      # relevant.
+      t.string :context_key, null: false
+      t.integer :consistent_approvals, null: false, default: 0
+      # learning: still accumulating consistent_approvals toward the threshold.
+      # active: at or past the threshold - safe for a later commit to auto-
+      # settle this exact gate occurrence without ever pausing for a human.
+      # invalidated: a human rejected this exact gate occurrence at least
+      # once - terminal, permanent, never re-learned. A single rejection
+      # invalidates immediately, with no tolerance for "mostly consistent":
+      # see feat(rules) commits for the learning/auto-settle logic that
+      # enforces this.
+      t.string :status, null: false, default: "learning"
+      t.datetime :invalidated_at
+
+      t.timestamps
+    end
+
+    # Added here, not in create_belay_steps.rb.tt: belay_rules doesn't exist yet
+    # when that earlier migration runs, so the FK has to be added once this
+    # table does.
+    add_foreign_key :belay_steps, :belay_rules, column: :rule_applied_id
+
+    # One row per exact (workflow, workflow_version, gate_name, context_key)
+    # combination - a second consistent approval for the same gate occurrence
+    # updates this same row's counter rather than creating a sibling.
+    add_index :belay_rules, [:workflow, :workflow_version, :gate_name, :context_key],
+              unique: true, name: "index_belay_rules_on_identity"
+  end
+end

data/lib/generators/belay/install/templates/create_belay_runs.rb.tt

@@ -0,0 +1,37 @@
+class CreateBelayRuns < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    enable_extension "pgcrypto"
+
+    create_table :belay_runs, id: :uuid do |t|
+      t.string :workflow, null: false
+      t.string :workflow_version, null: false
+      t.jsonb :input, null: false, default: {}
+      t.string :status, null: false, default: "pending"
+      t.integer :current_position, null: false, default: 0
+      t.string :idempotency_key
+      t.string :lease_owner
+      t.datetime :lease_expires_at
+      t.jsonb :error
+      t.datetime :started_at
+      t.datetime :finished_at
+      # Both nil for an ordinary run - only set on a shadow run created by
+      # Run#replay. replay_of_id is a self-referential FK (added below, after
+      # create_table - Postgres can't reference a table from inside its own
+      # creation), not a NOT NULL/required column: most runs are not replays.
+      # replay_model is the model: override Run#replay was given, threaded
+      # through to Context#llm by Executor::StepRunner#build_context - a
+      # replayed llm_call step's own hardcoded model: in the workflow body is
+      # a default this overrides, not something replay edits in place.
+      t.uuid :replay_of_id
+      t.string :replay_model
+
+      t.timestamps
+    end
+
+    add_index :belay_runs, :idempotency_key, unique: true
+    add_index :belay_runs, [:status, :lease_expires_at]
+    add_index :belay_runs, :workflow
+    add_foreign_key :belay_runs, :belay_runs, column: :replay_of_id
+    add_index :belay_runs, :replay_of_id
+  end
+end

data/lib/generators/belay/install/templates/create_belay_steps.rb.tt

@@ -0,0 +1,58 @@
+class CreateBelaySteps < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :belay_steps, id: :uuid do |t|
+      t.uuid :run_id, null: false
+      t.integer :position, null: false
+      t.string :name, null: false
+      t.string :kind, null: false
+      t.string :status, null: false, default: "started"
+      t.jsonb :input
+      t.jsonb :output
+      t.string :provider
+      t.string :model
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.integer :cost_cents
+      t.integer :latency_ms
+      t.integer :attempt, null: false, default: 1
+      # Derived from run_id + position only (not attempt) so a retry of the same step
+      # presents the same key to an external API. See DESIGN_DECISIONS.md #3.
+      t.string :idempotency_key, null: false
+      t.jsonb :error
+      # Who/when resolved a needs_review step (Run#resolve_needs_review!) - named
+      # to match belay_approvals' decided_by/decided_at rather than invented fresh,
+      # same concept (a human recording a decision), different table because a
+      # needs_review resolution isn't a gate approval: there's no Belay::Approval
+      # row for it, and reusing that model (built and documented specifically
+      # around gates, including its unique-per-gate-step index) for an unrelated
+      # kind of step would overload what it means.
+      t.string :resolved_by
+      t.datetime :resolved_at
+      # Set by Context#llm when ctx.llm(..., cacheable: true) is served from
+      # belay_cache_entries instead of a real provider call - input_tokens/
+      # output_tokens/cost_cents/latency_ms all stay nil/0 for that same row,
+      # since nothing was actually billed.
+      t.boolean :cache_hit, null: false, default: false
+      # Only ever set on a GATE step, by Executor::StepRunner#auto_settle_gate!
+      # (a later commit) - identifies which belay_rules row auto-settled this
+      # gate without ever pausing for a human. nil for every step a human
+      # actually decided (manual approve!/reject!) and for every non-gate step.
+      # The FK into
+      # belay_rules lives in create_belay_rules.rb.tt, not here: that table is
+      # created by a LATER migration (belay_rules needs this column to already
+      # exist on belay_steps before it can reference it), so adding the FK from
+      # the later file is what keeps a fresh install's migrations individually
+      # valid in sequence.
+      t.uuid :rule_applied_id
+
+      t.timestamps
+    end
+
+    add_foreign_key :belay_steps, :belay_runs, column: :run_id
+
+    # The full history of attempts is kept (one row per attempt); this is what
+    # uniquely identifies a row, not a candidate key for the idempotency_key column
+    # above, which repeats across attempts by design.
+    add_index :belay_steps, [:run_id, :position, :attempt], unique: true
+  end
+end