belay 0.1.0

data/app/views/belay/runs/_step.html.erb

@@ -0,0 +1,52 @@
+<% error_message = step.error&.dig("message") || step.error&.dig("reason") %>
+
+<div class="flex gap-4">
+  <div class="flex flex-col items-center">
+    <div class="flex h-8 w-8 shrink-0 items-center justify-center rounded-full border border-slate-700 bg-slate-800
+                font-mono text-xs font-semibold text-slate-400">
+      <%= step.position %>
+    </div>
+    <div class="mt-1 w-px flex-1 bg-slate-800"></div>
+  </div>
+
+  <div class="card mb-4 flex-1 p-4">
+    <div class="mb-2 flex flex-wrap items-center justify-between gap-2">
+      <div class="flex items-center gap-2">
+        <span class="step-name font-medium text-slate-100"><%= step.name %></span>
+        <span class="rounded bg-slate-800 px-1.5 py-0.5 font-mono text-xs text-slate-400"><%= step.kind %></span>
+        <% if step.attempt > 1 %>
+          <span class="rounded bg-slate-800 px-1.5 py-0.5 font-mono text-xs text-slate-400">attempt <%= step.attempt %></span>
+        <% end %>
+      </div>
+      <span class="step-status"><%= status_badge(step.status) %></span>
+    </div>
+
+    <% if step.input.present? %>
+      <div class="mb-2">
+        <p class="field-label">Prompt</p>
+        <pre class="step-input overflow-x-auto whitespace-pre-wrap rounded bg-slate-950/60 p-2 font-mono text-xs text-slate-400"><%= step.input %></pre>
+      </div>
+    <% end %>
+
+    <% if step.output.present? %>
+      <div class="mb-2">
+        <p class="field-label">Response</p>
+        <pre class="step-output overflow-x-auto whitespace-pre-wrap rounded bg-slate-950/60 p-2 font-mono text-xs text-slate-400"><%= step.output %></pre>
+      </div>
+    <% end %>
+
+    <% if step.model.present? %>
+      <div class="flex flex-wrap gap-3 font-mono text-xs text-slate-500">
+        <span><%= step.model %></span>
+        <span><%= step.input_tokens %> in / <%= step.output_tokens %> out tokens</span>
+        <% if step.cost_cents %>
+          <span><%= number_to_currency(step.cost_cents / 100.0) %></span>
+        <% end %>
+      </div>
+    <% end %>
+
+    <% if error_message %>
+      <p class="step-error mt-2 rounded bg-rose-500/10 px-2 py-1 text-xs text-rose-300"><%= error_message %></p>
+    <% end %>
+  </div>
+</div>

data/app/views/belay/runs/diff.html.erb

@@ -0,0 +1,47 @@
+<h1 class="mb-1 text-lg font-semibold text-slate-100">Replay diff</h1>
+<p class="mb-6 text-sm text-slate-500">
+  <%= link_to @run.id, run_path(@run), class: "font-mono text-violet-300 hover:text-violet-200" %>
+  replayed from
+  <%= link_to @run.replay_of_id, run_path(@run.replay_of), class: "font-mono text-violet-300 hover:text-violet-200" %>
+  <% if @run.replay_model %>
+    using <code class="rounded bg-slate-800 px-1 py-0.5 font-mono text-xs text-slate-300"><%= @run.replay_model %></code>
+  <% end %>
+</p>
+
+<div class="card overflow-hidden">
+  <table class="min-w-full divide-y divide-slate-800 text-sm">
+    <thead class="bg-slate-900/80">
+      <tr>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Step</th>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Original output</th>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Replay output</th>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500"></th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-slate-800">
+      <% @diff.each do |entry| %>
+        <tr class="diff-row <%= "bg-amber-500/5" if entry[:changed] %>">
+          <td class="px-4 py-2">
+            <span class="font-medium text-slate-100"><%= entry[:name] %></span>
+            <span class="rounded bg-slate-800 px-1.5 py-0.5 font-mono text-xs text-slate-400"><%= entry[:kind] %></span>
+          </td>
+          <td class="px-4 py-2">
+            <pre class="whitespace-pre-wrap font-mono text-xs text-slate-400"><%= entry[:original_output] %></pre>
+          </td>
+          <td class="px-4 py-2">
+            <pre class="whitespace-pre-wrap font-mono text-xs text-slate-400"><%= entry[:replay_output] %></pre>
+          </td>
+          <td class="diff-status px-4 py-2 text-xs">
+            <% if !entry[:replayed] %>
+              <span class="rounded-full bg-slate-800 px-2 py-0.5 text-slate-400">not reached</span>
+            <% elsif entry[:changed] %>
+              <span class="rounded-full bg-amber-500/10 px-2 py-0.5 text-amber-400">changed</span>
+            <% else %>
+              <span class="rounded-full bg-emerald-500/10 px-2 py-0.5 text-emerald-400">unchanged</span>
+            <% end %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/belay/runs/index.html.erb

@@ -0,0 +1,60 @@
+<div class="mb-6 flex items-center justify-between">
+  <h1 class="text-xl font-semibold text-slate-100">Runs</h1>
+
+  <%= form_with url: runs_path, method: :get, local: true, class: "flex items-center gap-2" do |f| %>
+    <%= f.select :status, options_for_select(@statuses, params[:status]),
+                 { include_blank: "All statuses" }, class: "select-field" %>
+    <%= f.select :workflow, options_for_select(@workflows, params[:workflow]),
+                 { include_blank: "All workflows" }, class: "select-field" %>
+    <%= f.submit "Filter", class: "btn-secondary" %>
+  <% end %>
+</div>
+
+<% if @runs.any? %>
+  <div class="card overflow-hidden">
+    <table class="min-w-full divide-y divide-slate-800 text-sm">
+      <thead class="bg-slate-900/80">
+        <tr>
+          <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Workflow</th>
+          <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Status</th>
+          <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Started</th>
+          <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Finished</th>
+        </tr>
+      </thead>
+      <tbody class="divide-y divide-slate-800">
+        <% @runs.each do |run| %>
+          <tr class="hover:bg-slate-800/60">
+            <td class="px-4 py-2">
+              <%= link_to run.workflow, run_path(run, return_to: request.fullpath),
+                          class: "run-workflow font-medium text-violet-300 hover:text-violet-200" %>
+            </td>
+            <td class="run-status px-4 py-2"><%= status_badge(run.status) %></td>
+            <td class="px-4 py-2 font-mono text-xs text-slate-500"><%= run.started_at %></td>
+            <td class="px-4 py-2 font-mono text-xs text-slate-500"><%= run.finished_at %></td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+  <% if @total_pages > 1 %>
+    <div class="mt-4 flex items-center justify-between text-sm">
+      <% if @page > 1 %>
+        <%= link_to "← Previous", runs_path(pagination_params(request, @page - 1)), class: "pagination-prev btn-secondary" %>
+      <% else %>
+        <span class="btn-secondary pointer-events-none opacity-40">← Previous</span>
+      <% end %>
+
+      <span class="pagination-status text-slate-400">Page <%= @page %> of <%= @total_pages %></span>
+
+      <% if @page < @total_pages %>
+        <%= link_to "Next →", runs_path(pagination_params(request, @page + 1)), class: "pagination-next btn-secondary" %>
+      <% else %>
+        <span class="btn-secondary pointer-events-none opacity-40">Next →</span>
+      <% end %>
+    </div>
+  <% end %>
+<% else %>
+  <div class="card border-dashed px-6 py-12 text-center">
+    <p class="text-sm text-slate-500">No runs yet.</p>
+  </div>
+<% end %>

data/app/views/belay/runs/show.html.erb

@@ -0,0 +1,34 @@
+<%= link_to "← Back to runs", back_to_runs_path(request),
+            class: "back-to-runs mb-4 inline-flex items-center gap-1 text-sm text-slate-400 hover:text-slate-100" %>
+
+<%= render "belay/runs/header" %>
+
+<% if @run.replay_of %>
+  <%= render "belay/runs/replayed_from" %>
+<% end %>
+
+<% if @run.replays.any? %>
+  <%= render "belay/runs/replays" %>
+<% end %>
+
+<% if @run.pending_gate %>
+  <%= render "belay/runs/pending_gate" %>
+<% end %>
+
+<%# Not rendered for a replay shadow (@run.replay_of present) even if it has
+    one: resolve_needs_review! expects a run flag_needs_review! actually
+    paused, which seeding a shadow's rows never does - calling it here would
+    either raise a confusing InvalidTransitionError or, for outcome: "failed",
+    silently "resolve" a run that was never really awaiting a human in the
+    first place. A shadow's needs_review row means "the original didn't
+    cleanly pass this point, reproduced for visibility" - look at #replay_of
+    to resolve the real thing, not this mirror of it. %>
+<% if @run.pending_needs_review && !@run.replay_of %>
+  <%= render "belay/runs/pending_needs_review" %>
+<% end %>
+
+<h2 class="mb-4 text-sm font-semibold uppercase tracking-wide text-slate-500">Steps</h2>
+
+<div>
+  <%= render partial: "belay/runs/step", collection: @steps, as: :step %>
+</div>

data/app/views/belay/shared/_flash.html.erb

@@ -0,0 +1,11 @@
+<% if notice %>
+  <div class="mb-6 rounded-md border border-emerald-500/20 bg-emerald-500/10 px-4 py-3 text-sm text-emerald-300" role="status">
+    <%= notice %>
+  </div>
+<% end %>
+
+<% if alert %>
+  <div class="mb-6 rounded-md border border-rose-500/20 bg-rose-500/10 px-4 py-3 text-sm text-rose-300" role="alert">
+    <%= alert %>
+  </div>
+<% end %>

data/app/views/belay/shared/_sidebar.html.erb

@@ -0,0 +1,22 @@
+<aside class="flex w-56 shrink-0 flex-col gap-6 border-r border-slate-800 bg-slate-900/60 px-4 py-6">
+  <div class="px-2">
+    <%= link_to runs_path, class: "flex items-center gap-2 text-base font-semibold text-slate-100" do %>
+      <span class="h-2 w-2 rounded-sm bg-violet-400"></span>
+      Belay
+    <% end %>
+    <p class="mt-1 text-xs text-slate-500">durable AI runs</p>
+  </div>
+
+  <nav class="flex flex-col gap-1 text-sm">
+    <%= link_to runs_path,
+                class: "rounded-md px-3 py-2 font-medium #{current_page?(runs_path) ? 'bg-violet-500/10 text-slate-100' : 'text-slate-400 hover:bg-slate-800 hover:text-slate-100'}" do %>
+      Runs
+    <% end %>
+    <%= link_to stats_path,
+                class: "rounded-md px-3 py-2 font-medium #{current_page?(stats_path) ? 'bg-violet-500/10 text-slate-100' : 'text-slate-400 hover:bg-slate-800 hover:text-slate-100'}" do %>
+      Stats
+    <% end %>
+  </nav>
+
+  <p class="mt-auto px-2 text-xs text-slate-600">mounted at /belay</p>
+</aside>

data/app/views/belay/stats/_chart.html.erb

@@ -0,0 +1,56 @@
+<%
+  # Bar height is a computed percentage, not a Tailwind utility class - an
+  # interpolated class string like "h-[#{pct}%]" wouldn't be seen by
+  # Tailwind's build-time content scanner (it reads the template's literal
+  # source text, not its rendered output), so it would compile away to
+  # nothing. A plain inline style is the correct tool here, not a workaround.
+  #
+  # Gridlines round UP to the next clean multiple of 20 above the real max,
+  # not the raw max itself - an axis that tops out at an arbitrary value like
+  # "83.4" reads as noise; "100" is a value a glance can actually anchor to.
+  raw_max = daily_stats.map(&:calls_per_100_runs).max.to_f
+  axis_max = raw_max.zero? ? 20.0 : (raw_max / 20.0).ceil * 20.0
+  gridlines = [axis_max, axis_max * 0.75, axis_max * 0.5, axis_max * 0.25, 0]
+%>
+<div class="card mb-6 p-6">
+  <h2 class="text-xs font-semibold uppercase tracking-wide text-slate-500">Calls per 100 runs</h2>
+
+  <div class="mt-6 flex h-48">
+    <div class="flex w-7 flex-col justify-between pb-6 pr-2 text-right">
+      <% gridlines.each do |value| %>
+        <span class="font-mono text-[10px] leading-none text-slate-600"><%= value.to_i %></span>
+      <% end %>
+    </div>
+
+    <div class="relative flex-1">
+      <div class="absolute inset-0 flex flex-col justify-between pb-6">
+        <% gridlines.each do %>
+          <div class="border-t border-slate-800"></div>
+        <% end %>
+      </div>
+
+      <%# No items-end here - each bar-col needs its OWN definite height (via the
+          default stretch) for its bar's percentage height to resolve against;
+          justify-end on each bar-col below is what actually bottom-anchors it. %>
+      <div class="absolute inset-0 z-10 flex gap-2 pb-6">
+        <% daily_stats.each_with_index do |day, index| %>
+          <% is_endpoint = index == daily_stats.size - 1 %>
+          <div class="group flex flex-1 flex-col items-center justify-end gap-1.5"
+               title="<%= day.date %>: <%= day.calls_per_100_runs %> per 100 runs (<%= day.real_calls %> calls, <%= day.runs %> runs)">
+            <% if is_endpoint %>
+              <span class="stat-rate-label font-mono text-[11px] font-medium text-slate-200"><%= day.calls_per_100_runs %></span>
+            <% end %>
+            <div class="w-full max-w-[22px] rounded-t <%= is_endpoint ? "bg-violet-400" : "bg-violet-500/40 group-hover:bg-violet-400/70" %>"
+                 style="height: <%= [(day.calls_per_100_runs / axis_max * 100), 1.5].max.round(1) %>%"></div>
+          </div>
+        <% end %>
+      </div>
+
+      <div class="pointer-events-none absolute inset-x-0 bottom-0 flex gap-2">
+        <% daily_stats.each do |day| %>
+          <span class="flex-1 text-center font-mono text-[10px] text-slate-600"><%= day.date.strftime("%-m/%-d") %></span>
+        <% end %>
+      </div>
+    </div>
+  </div>
+</div>

data/app/views/belay/stats/_table.html.erb

@@ -0,0 +1,22 @@
+<div class="card overflow-hidden">
+  <table class="min-w-full divide-y divide-slate-800 text-sm">
+    <thead class="bg-slate-900/80">
+      <tr>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Date</th>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Runs</th>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Real API calls</th>
+        <th class="px-4 py-2 text-left text-xs font-medium uppercase tracking-wide text-slate-500">Per 100 runs</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-slate-800">
+      <% daily_stats.each do |day| %>
+        <tr class="hover:bg-slate-800/60">
+          <td class="stat-date px-4 py-2 font-mono text-xs text-slate-300"><%= day.date %></td>
+          <td class="stat-runs px-4 py-2 font-mono text-xs text-slate-500"><%= day.runs %></td>
+          <td class="stat-calls px-4 py-2 font-mono text-xs text-slate-500"><%= day.real_calls %></td>
+          <td class="stat-rate px-4 py-2 font-mono text-xs font-medium text-slate-100"><%= day.calls_per_100_runs %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>

data/app/views/belay/stats/index.html.erb

@@ -0,0 +1,16 @@
+<div class="mb-6">
+  <h1 class="text-xl font-semibold text-slate-100">Cost</h1>
+  <p class="mt-1 text-sm text-slate-500">
+    Real provider calls per 100 runs, by day. A cache hit or a rule-auto-settled gate
+    makes no call at all, so a falling trend here is the cost-reduction features working.
+  </p>
+</div>
+
+<% if @daily_stats.any? %>
+  <%= render "chart", daily_stats: @daily_stats %>
+  <%= render "table", daily_stats: @daily_stats %>
+<% else %>
+  <div class="card border-dashed px-6 py-12 text-center">
+    <p class="text-sm text-slate-500">No runs yet.</p>
+  </div>
+<% end %>

data/app/views/layouts/belay/application.html.erb

@@ -0,0 +1,19 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Belay</title>
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <style><%= raw Belay::Engine.stylesheet %><%= raw Belay.config.custom_css %></style>
+  </head>
+  <body class="flex min-h-screen bg-slate-950 font-sans text-slate-100 antialiased">
+    <%= render "belay/shared/sidebar" %>
+
+    <main class="min-w-0 flex-1 px-6 py-8 sm:px-10">
+      <div class="mx-auto max-w-4xl">
+        <%= render "belay/shared/flash" %>
+        <%= yield %>
+      </div>
+    </main>
+  </body>
+</html>

data/config/routes.rb

@@ -0,0 +1,13 @@
+Belay::Engine.routes.draw do
+  resources :runs, only: [:index, :show] do
+    member do
+      post :approve
+      post :reject
+      post :resolve
+      get :diff
+    end
+  end
+  get "stats", to: "stats#index"
+
+  root to: "runs#index"
+end

data/lib/belay/anthropic_provider.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Belay
+  # Calls Anthropic's Messages API directly over Net::HTTP (stdlib) rather than via
+  # the official anthropic gem - see belay-planning/DECISIONS.md for the reasoning:
+  # this gem already has one cross-version dependency incident (the json/
+  # activesupport quirks_mode break on Rails 7.1, see gemfiles/rails_7_1.gemfile),
+  # and a provider this central shouldn't add a second gem's own version matrix to
+  # track. The wire format needed here - POST a JSON body, read a JSON body back -
+  # is small enough that stdlib Net::HTTP plus JSON covers it without one.
+  #
+  # Endpoint and headers verified against Anthropic's Messages API docs as of
+  # 2026-10-19 (anthropic-version: 2023-06-01 is still the current, required
+  # version string).
+  #
+  # schema: uses Anthropic's structured outputs (top-level output_config.format,
+  # type: "json_schema"), not forced tool_choice. An earlier draft of this file used
+  # tool_choice: {type: "tool", name: ...}, which 400s outright on Claude Opus 5.5,
+  # Sonnet 5.5, Fable 5.1 and Mythos 5.1 - i.e. it would have broken on exactly the
+  # model this file's own README example calls. output_config.format works across
+  # the current model lineup, so that's what's implemented. Any object in schema:
+  # needs additionalProperties: false, per Anthropic's own requirement for this
+  # field - not validated here; an object schema missing it surfaces as a 400
+  # (RequestError), same as any other malformed request.
+  #
+  # stop_reason is checked before parsing: "refusal" means Claude declined to
+  # produce schema-matching output at all, "max_tokens" means what came back may be
+  # truncated mid-JSON. Both raise StructuredOutputError with that reason rather
+  # than attempt JSON.parse on text that may not actually be valid JSON.
+  #
+  # Deliberately does NOT ship a baked-in per-model price table. Anthropic's prices
+  # change, this gem has no way to keep a hardcoded table current, and a silently
+  # stale number is worse than an honest nil - the same reasoning ProviderResponse's
+  # own comment gives for why cost_cents defaults to nil at all. Pass pricing: with
+  # rates for whichever models you actually use; cost_cents is nil for any model not
+  # in it, same as it would be if usage data were missing entirely.
+  class AnthropicProvider < Provider
+    API_URL = URI("https://api.anthropic.com/v1/messages")
+    API_VERSION = "2023-06-01"
+
+    # Raised on any non-2xx response. Anthropic's own error body (JSON, usually
+    # {"error": {"type":, "message":}}) is preserved verbatim in the message rather
+    # than parsed and re-interpreted, so whatever Anthropic actually said is visible
+    # in the step's recorded error, not lossily summarized.
+    class RequestError < Error
+      attr_reader :status
+
+      def initialize(status:, body:)
+        @status = status
+        super("Anthropic API request failed with status #{status}: #{body}")
+      end
+    end
+
+    # Raised when schema: was given but Claude's response can't be trusted to
+    # contain valid, complete schema-matching JSON. reason: is Anthropic's own
+    # stop_reason ("refusal" or "max_tokens"), exposed so a caller can tell "ask a
+    # human" (refusal) apart from "retry with a higher max_tokens" (max_tokens),
+    # rather than both surfacing as the same undifferentiated Belay::Error.
+    class StructuredOutputError < Error
+      attr_reader :reason, :response
+
+      def initialize(reason:, response:)
+        @reason = reason
+        @response = response
+        super("Anthropic did not return schema-matching output (stop_reason: #{reason.inspect}): #{response.inspect}")
+      end
+    end
+
+    # pricing: {"claude-..." => { input_per_million: <USD Float>, output_per_million: <USD Float> }, ...}
+    #
+    # max_tokens: counts thinking tokens too on models with thinking enabled by
+    # default (e.g. Claude Opus 5) - a schema: call can hit max_tokens, and raise
+    # StructuredOutputError, more easily than the number alone suggests. Raise this
+    # if that happens in practice; there's no way to size it correctly up front
+    # without knowing the model and its thinking behavior.
+    def initialize(api_key: ENV.fetch("ANTHROPIC_API_KEY", nil), max_tokens: 4096, pricing: {})
+      super()
+      raise ArgumentError, "#{self.class} requires api_key: (or ANTHROPIC_API_KEY)" if api_key.nil?
+
+      @api_key = api_key
+      @max_tokens = max_tokens
+      @pricing = pricing
+    end
+
+    def call(model:, prompt:, schema: nil)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      status, body = perform_request(request_body(model: model, prompt: prompt, schema: schema))
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+
+      raise RequestError.new(status: status, body: body) unless status.between?(200, 299)
+
+      build_response(JSON.parse(body), model: model, schema: schema, latency_ms: latency_ms)
+    end
+
+    private
+
+    def request_body(model:, prompt:, schema:)
+      body = { model: model, max_tokens: @max_tokens, messages: [{ role: "user", content: prompt }] }
+      return body if schema.nil?
+
+      body.merge(output_config: { format: { type: "json_schema", schema: schema } })
+    end
+
+    def perform_request(body)
+      response = Net::HTTP.post(API_URL, JSON.generate(body), request_headers)
+      [response.code.to_i, response.body]
+    end
+
+    def request_headers
+      {
+        "x-api-key" => @api_key,
+        "anthropic-version" => API_VERSION,
+        "content-type" => "application/json"
+      }
+    end
+
+    def build_response(response, model:, schema:, latency_ms:)
+      usage = response["usage"] || {}
+      input_tokens, output_tokens = usage.values_at("input_tokens", "output_tokens")
+
+      ProviderResponse.new(
+        content: extract_content(response, schema: schema),
+        model: response["model"] || model,
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        cost_cents: cost_cents(model: model, input_tokens: input_tokens, output_tokens: output_tokens),
+        latency_ms: latency_ms
+      )
+    end
+
+    def extract_content(response, schema:)
+      schema ? extract_structured_output(response) : extract_text(response["content"] || [])
+    end
+
+    def extract_structured_output(response)
+      stop_reason = response["stop_reason"]
+      if %w[refusal max_tokens].include?(stop_reason)
+        raise StructuredOutputError.new(reason: stop_reason, response: response)
+      end
+
+      JSON.parse(extract_text(response["content"] || []))
+    end
+
+    def extract_text(blocks)
+      block = blocks.find { |b| b["type"] == "text" }
+      raise Error, "Anthropic response had no text content block" if block.nil?
+
+      block["text"]
+    end
+
+    def cost_cents(model:, input_tokens:, output_tokens:)
+      return nil if input_tokens.nil? || output_tokens.nil?
+
+      rates = @pricing[model]
+      return nil if rates.nil?
+
+      input_cost = input_tokens * rates.fetch(:input_per_million)
+      output_cost = output_tokens * rates.fetch(:output_per_million)
+      ((input_cost + output_cost) / 1_000_000.0 * 100).round
+    end
+  end
+end

data/lib/belay/application_record.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Belay
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/lib/belay/approval.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Belay
+  class Approval < ApplicationRecord
+    self.table_name = "belay_approvals"
+
+    # Explicit class_name and optional: false for the same reason Step declares
+    # them this way: no Zeitwerk/app-autoloading here to infer the namespace from,
+    # and optional: false stated explicitly doesn't depend on the host app's
+    # load_defaults to get a friendly validation error instead of a raw DB
+    # NotNullViolation.
+    belongs_to :run, class_name: "Belay::Run", optional: false
+    belongs_to :step, class_name: "Belay::Step", optional: false
+
+    enum :status, {
+      pending: "pending",
+      approved: "approved",
+      rejected: "rejected"
+    }
+
+    # status has a DB default ("pending"), 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. Matches Step's own comment on the identical situation.
+    validates :status, presence: true
+
+    # No approve!/reject! here. Those are Run methods (feat(runs): add approve! and
+    # reject! that enqueue ResumeRunJob, not this commit) - a decision resolves the
+    # RUN's pending gate, not just this row in isolation, the same reason
+    # transitions live on Run rather than Step: Belay::Run#start!/pause!/etc. own
+    # the run-level policy, and Step has no bang methods of its own either (see its
+    # comment on exactly this). Adding them here now would mean rebuilding them
+    # once that policy exists, same as Step's own stated reasoning.
+  end
+end

data/lib/belay/cache_entry.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Belay
+  # Backs ctx.llm(..., cacheable: true) - see Context#llm. Not a general-
+  # purpose cache for anything else in the gem; the only two callers are
+  # Context#llm's own fetch-then-store pair.
+  class CacheEntry < ApplicationRecord
+    self.table_name = "belay_cache_entries"
+
+    # SHA256 of [provider class name, model, prompt, schema].inspect - exact,
+    # literal match only, the same .inspect-of-an-array-then-hash pattern
+    # Workflow.workflow_version already uses. Deliberately NOT normalized
+    # (schema/prompt symbol vs string key differences hash differently,
+    # on purpose) - "exact-match cache" means exactly that, not "semantically
+    # equivalent"; normalizing would be extra logic in service of a kind of
+    # match this feature was never meant to offer.
+    #
+    # provider.class.name, not the model: string alone - a cached entry from
+    # one provider should never satisfy a lookup under a different one
+    # (swapping Belay.config.provider mid-lifecycle, or a FakeProvider in
+    # tests sharing a database with a real one, shouldn't silently reuse
+    # whatever the other provider once returned for an identical-looking call).
+    def self.key_for(provider:, model:, prompt:, schema:)
+      Digest::SHA256.hexdigest([provider.class.name, model, prompt, schema].inspect)
+    end
+
+    # nil on a miss OR an expired entry - the caller (Context#llm) can't tell
+    # those apart from this return value alone, and doesn't need to: either
+    # way, it makes a real provider call next. An expired row is left in
+    # place, not deleted here - store! below will overwrite it on the next
+    # successful call for the same key; there's no background sweep for rows
+    # that are never asked for again, same as belay_steps keeps every row
+    # forever rather than pruning anything.
+    def self.fetch(provider:, model:, prompt:, schema:)
+      entry = find_by(key: key_for(provider: provider, model: model, prompt: prompt, schema: schema))
+      return nil if entry.nil? || entry.expires_at&.past?
+
+      entry.increment!(:hits)
+      entry.content
+    end
+
+    # upsert, not create!/update! - two callers racing to cache the same miss
+    # (two workers asking the identical question for the first time at once)
+    # both reach here; upsert's ON CONFLICT DO UPDATE means the second one
+    # overwrites the first cleanly instead of raising on the unique index,
+    # the same reasoning Run#acquire_lease! and friends already lean on
+    # Postgres for elsewhere in this gem rather than a read-then-write race.
+    #
+    # ttl: defaults to the CURRENT Belay.config.cache_ttl at call time, not
+    # whatever it was when an older entry for this key was first stored -
+    # every store! reads it fresh, so changing the config takes effect on the
+    # very next cache miss, not retroactively on rows already written.
+    # rubocop:disable-next Metrics/ParameterLists
+    def self.store!(provider:, model:, prompt:, schema:, content:, ttl: Belay.config.cache_ttl)
+      key_value = key_for(provider: provider, model: model, prompt: prompt, schema: schema)
+      now = Time.current
+      upsert(
+        { key: key_value, content: content, hits: 0, expires_at: ttl && (now + ttl), created_at: now, updated_at: now },
+        unique_by: :key
+      )
+    end
+  end
+end