acts_as_calculator_editor 0.1.0

data/app/controllers/acts_as_calculator_editor/templates_controller.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # Templates get version history, not effective-dating — there are no `effective_from`
+  # /`effective_to` columns and no UI here should imply otherwise
+  # (docs/core-gem-contract.md §2.5). Changing a body publishes a new row
+  # (`PublishTemplate`); undoing one points `current` back at an older row
+  # (`PromoteTemplate`). Neither is an update, which is why there is no `update` action.
+  #
+  # `new?from_id=` prefills from an existing template, which is the "edit this template"
+  # affordance: it lands as a new version rather than a rewrite of the old one.
+  class TemplatesController < ApplicationController
+    def index
+      @templates = filter_by_key_and_scope(scoped_templates)
+      @history = history?
+    end
+
+    def show
+      @template = template
+      @siblings = ActsAsCalculator::Template.version_siblings_of(template).latest_first
+    end
+
+    def new
+      @form = prefilled_form
+    end
+
+    def create
+      @form = submitted_form
+
+      rescuing_core_errors(:new) do
+        published = ActsAsCalculator::PublishTemplate.(**template_attributes)
+        redirect_to template_path(published),
+                    notice: "Published version #{published.version_number} of #{published.key}."
+      end
+    end
+
+    def destroy
+      template.destroy!
+      redirect_to templates_path, notice: "Deleted #{template.key} version #{template.version_number}."
+    end
+
+    # Rollback. The row that went wrong stays in the history; `current` just stops pointing
+    # at it.
+    def promote
+      promoted = ActsAsCalculator::PromoteTemplate.(template:)
+      redirect_to template_path(promoted),
+                  notice: "Version #{promoted.version_number} of #{promoted.key} is now current."
+    end
+
+    # Renders whatever body was posted, through the real Liquid sandbox, against a synthetic
+    # `Result` — no persisted template, no throwaway version row (contract §4.3). The member
+    # route falls back to the stored body so a saved template can be previewed from its own
+    # page; the collection route is what the new-template form posts to while typing.
+    #
+    # `ActsAsCalculator::TemplateRenderError` carries Liquid's own line number, so a failure
+    # is shown in the preview pane rather than swallowed.
+    def preview
+      @template = params[:id].present? ? template : nil
+      @preview_format = preview_format
+      @preview_body = RenderTemplatePreview.(body: preview_source, format: @preview_format,
+                                             context: params[:context])
+      render :preview
+    rescue ActsAsCalculator::Error => e
+      @preview_error = e.message
+      render :preview, status: :unprocessable_entity
+    end
+
+    private
+
+    def template
+      @template ||= ActsAsCalculator::Template.find(params[:id])
+    end
+
+    # Current versions only unless asked otherwise: a list of every version of every
+    # template is history, not the thing an operator came to look at.
+    def scoped_templates
+      relation = ActsAsCalculator::Template.order(:scope, :key, version_number: :desc)
+      history? ? relation : relation.current
+    end
+
+    def history?
+      %w[true 1].include?(params[:history].to_s)
+    end
+
+    def prefilled_form
+      source = params[:from_id].presence && ActsAsCalculator::Template.find(params[:from_id])
+      return blank_form if source.nil?
+
+      { "key" => source.key, "scope" => source.scope, "format" => source.format, "body" => source.body }
+    end
+
+    def blank_form
+      { "key" => "", "scope" => ActsAsCalculator::DEFAULT_SCOPE,
+        "format" => ActsAsCalculator::Template::HTML, "body" => "" }
+    end
+
+    def submitted_form
+      permitted = template_params
+
+      { "key" => permitted[:key].to_s, "scope" => permitted[:scope].to_s,
+        "format" => permitted[:format].to_s, "body" => permitted[:body].to_s }
+    end
+
+    def template_params
+      params.require(:template).permit(:key, :scope, :format, :body)
+    end
+
+    def template_attributes
+      { key: @form["key"],
+        body: @form["body"],
+        scope: @form["scope"].presence,
+        format: @form["format"].presence || ActsAsCalculator::Template::HTML,
+        owner: current_owner }
+    end
+
+    def preview_source
+      posted = params.dig(:template, :body)
+      return posted.to_s if posted.present?
+
+      params[:id].present? ? template.body : ""
+    end
+
+    def preview_format
+      posted = params.dig(:template, :format)
+      return posted.to_s if ActsAsCalculator::Template::FORMATS.include?(posted.to_s)
+
+      params[:id].present? ? template.format : ActsAsCalculator::Template::HTML
+    end
+  end
+end

data/app/controllers/acts_as_calculator_editor/validations_controller.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  # The engine's only JSON endpoint, and the exception that proves the rule in
+  # docs/core-gem-contract.md §1: this is a live-typing helper for the expression field, not
+  # a CRUD surface. It reads nothing but lookup-table existence and writes nothing at all.
+  #
+  # Debounce it from the client. It parses an expression and runs at most one indexed lookup
+  # per declared `lookup` variable, so it is cheap — but it is still a request per keystroke
+  # if nobody says otherwise.
+  class ValidationsController < ApplicationController
+    # Forced rather than negotiated so a `fetch` that forgets its Accept header still gets
+    # JSON back, including for the error paths in `ApplicationController`.
+    before_action { request.format = :json }
+
+    def create
+      render json: ValidateExpression.(expression: params[:expression],
+                                       variables: CastVariableRows.(params[:variables]),
+                                       scope: params[:scope],
+                                       owner: current_owner)
+    end
+  end
+end

data/app/helpers/acts_as_calculator_editor/application_helper.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  module ApplicationHelper
+    # Derived at runtime, never hardcoded. docs/core-gem-contract.md §5 is explicit about
+    # why: a host app may register its own functions into the same registry, so a list
+    # copied into JavaScript goes stale the moment somebody does. The autocomplete and the
+    # "unknown function" colouring both read this.
+    #
+    # `Dentaku::AST::Function.registry` holds the builtins (57 of them); the gem's own
+    # `FunctionRegistry.default` holds `bracket`, `progressive_bracket`, `round_currency` and
+    # `prorate` plus anything the host added. Names come back in mixed shapes across the two,
+    # so they are folded to strings and uniqued case-insensitively — matching Dentaku's own
+    # case-insensitive resolution.
+    def calculator_function_names
+      @calculator_function_names ||= begin
+        gem_functions = ActsAsCalculator::FunctionRegistry.default.to_a.map { |fn| fn.name.to_s }
+        builtins = Dentaku::AST::Function.registry.keys.map(&:to_s)
+
+        (gem_functions + builtins).uniq(&:downcase).sort
+      rescue StandardError
+        # A registry shape change upstream must not take the whole form down with it — the
+        # editor degrades to "no autocomplete", and the server-side check still catches an
+        # undefined function name.
+        []
+      end
+    end
+
+    # Turbo must not touch a file response: it has no way to render one, and swallowing the
+    # navigation leaves the operator on the page with nothing downloaded.
+    def export_link_options(extra = {})
+      { data: { turbo: false } }.deep_merge(extra)
+    end
+
+    NAV_BASE = "rounded-md px-3 py-1.5 font-medium transition-colors"
+
+    def nav_class(current)
+      if current
+        "#{NAV_BASE} bg-slate-900 text-white"
+      else
+        "#{NAV_BASE} text-slate-600 hover:bg-slate-100 hover:text-slate-900"
+      end
+    end
+
+    # Shared input chrome, so a field looks the same on every form without each view
+    # restating a dozen utility classes.
+    def field_class(extra = nil)
+      base = "block w-full rounded-md border border-slate-300 bg-white px-3 py-2 text-sm " \
+             "shadow-sm placeholder:text-slate-400 focus:border-slate-500 focus:outline-none " \
+             "focus:ring-2 focus:ring-slate-200 disabled:bg-slate-100 read-only:bg-slate-100"
+      [base, extra].compact.join(" ")
+    end
+
+    def label_class
+      "mb-1 block text-sm font-medium text-slate-700"
+    end
+
+    def hint_class
+      "mt-1 block text-xs text-slate-500"
+    end
+
+    def button_class(variant = :primary)
+      base = "inline-flex items-center justify-center rounded-md px-3 py-2 text-sm font-medium " \
+             "transition-colors focus:outline-none focus:ring-2 focus:ring-offset-1"
+      variants = {
+        primary: "bg-slate-900 text-white hover:bg-slate-700 focus:ring-slate-400",
+        danger: "bg-white text-red-700 border border-red-300 hover:bg-red-50 focus:ring-red-300",
+        secondary: "bg-white text-slate-700 border border-slate-300 hover:bg-slate-50 focus:ring-slate-300"
+      }
+      "#{base} #{variants.fetch(variant, variants[:secondary])}"
+    end
+
+    # A status pill for a formula version or template row.
+    def status_badge(status)
+      palette = {
+        "active" => "bg-emerald-100 text-emerald-800",
+        "draft" => "bg-amber-100 text-amber-800",
+        "retired" => "bg-slate-200 text-slate-600"
+      }
+      classes = "inline-flex rounded-full px-2 py-0.5 text-xs font-medium " \
+                "#{palette.fetch(status.to_s, "bg-slate-200 text-slate-600")}"
+      tag.span(status, class: classes)
+    end
+  end
+end

data/app/jobs/acts_as_calculator_editor/application_job.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/mailers/acts_as_calculator_editor/application_mailer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module ActsAsCalculatorEditor
+  class ApplicationMailer < ActionMailer::Base
+    default from: "from@example.com"
+    layout "mailer"
+  end
+end

data/app/models/acts_as_calculator_editor/application_record.rb

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

data/app/views/acts_as_calculator_editor/formula_versions/_expression_field.html.erb

@@ -0,0 +1,64 @@
+<%# The formula expression editor. NOT a rich text editor, and specifically not Lexxy —
+    docs/lexxy-decision.md §3 demonstrates the bug: Lexxy's value contract is HTML, `<` is a
+    Dentaku operator, and `salary <bonus` round-trips through an HTML parser as `salary `,
+    which still parses as valid Dentaku and quietly computes a different number.
+
+    So the field is a real <textarea> that keeps its `name` and `id`. The colour comes from a
+    <pre> sitting behind it: the textarea's own text is transparent (only its caret is
+    visible), the <pre> holds the same characters wrapped in coloured spans, and the two
+    scroll together. Nothing in the overlay can reach the submitted value.
+
+    Both elements MUST agree on font, size, line-height, padding, border width and wrapping,
+    or the coloured text drifts away from the caret. That pairing lives in
+    `.aac-expression__ink` / `.aac-expression__overlay` in the stylesheet — change one and
+    change the other. %>
+<div class="aac-expression"
+     data-controller="expression-editor"
+     data-expression-editor-validate-url-value="<%= validations_path %>"
+     data-expression-editor-scope-value="<%= @formula.scope %>"
+     data-expression-editor-functions-value="<%= calculator_function_names.to_json %>">
+
+  <%= label_tag "version_expression", "Expression", class: label_class %>
+
+  <div class="aac-expression__shell">
+    <pre class="aac-expression__overlay" aria-hidden="true"
+         data-expression-editor-target="highlight"></pre>
+
+    <%= text_area_tag "version[expression]", value,
+                      id: "version_expression",
+                      rows: 3,
+                      spellcheck: false,
+                      autocomplete: "off",
+                      autocapitalize: "off",
+                      autocorrect: "off",
+                      class: "aac-expression__ink",
+                      role: "combobox",
+                      aria: { expanded: "false", autocomplete: "list", controls: "version_expression_suggestions" },
+                      data: {
+                        editor_target: "expression",
+                        expression_editor_target: "input",
+                        action: "input->expression-editor#onInput " \
+                                "scroll->expression-editor#syncScroll " \
+                                "keydown->expression-editor#onKeydown " \
+                                "blur->expression-editor#onBlur " \
+                                "click->expression-editor#refreshSuggestions"
+                      } %>
+
+    <ul class="aac-suggestions" role="listbox" hidden
+        id="version_expression_suggestions"
+        aria-label="Functions and declared variables"
+        data-expression-editor-target="suggestions"></ul>
+  </div>
+
+  <p class="<%= hint_class %>">
+    Operators <code>+ - * / % ^</code>, comparisons <code>&lt; &gt; &lt;= &gt;= == !=</code>,
+    <code>and</code> / <code>or</code>. Use <code>not(x)</code>, not <code>!x</code>, and
+    <code>^</code>, not <code>**</code>. Start typing a name for functions and declared
+    variables.
+  </p>
+
+  <%# aria-live so the debounced result is announced without moving focus. %>
+  <div class="aac-expression__status mt-2 space-y-1"
+       role="status" aria-live="polite"
+       data-expression-editor-target="status"></div>
+</div>

data/app/views/acts_as_calculator_editor/formula_versions/_variable_fields.html.erb

@@ -0,0 +1,51 @@
+<%# Index-keyed rather than `[]`-appended: Rack closes an array-of-hashes element when it
+    sees a repeated key, so a row whose only differing field is a checkbox can merge into
+    its neighbour. `CastVariableRows` accepts either shape; this one cannot go wrong.
+
+    Renaming a variable re-colours the expression above and re-runs the debounced check
+    without a reload. That is NOT wired with `data-action` here: these rows are a sibling
+    section of the form, not descendants of the `expression-editor` element, and a Stimulus
+    action only routes to a controller found on an ancestor — so a `data-action` written here
+    fires nothing at all. The controller listens for `input`/`change` on the whole form
+    instead; see its `connect`. %>
+<fieldset class="variable-row grid gap-3 rounded-md border border-slate-200 bg-slate-50 p-3 sm:grid-cols-12">
+  <div class="sm:col-span-3">
+    <%= label_tag "version_variables_#{index}_name", "Name", class: label_class %>
+    <%= text_field_tag "version[variables][#{index}][name]", row["name"],
+                       id: "version_variables_#{index}_name",
+                       class: field_class("font-mono"),
+                       autocomplete: "off",
+                       spellcheck: false %>
+  </div>
+
+  <div class="sm:col-span-3">
+    <%= label_tag "version_variables_#{index}_source_type", "Source", class: label_class %>
+    <%= select_tag "version[variables][#{index}][source_type]",
+                   options_for_select(ActsAsCalculator::ResolveVariables::SOURCE_TYPES.map(&:to_s),
+                                      row["source_type"].presence || "context"),
+                   id: "version_variables_#{index}_source_type",
+                   class: field_class %>
+  </div>
+
+  <div class="sm:col-span-4">
+    <%= label_tag "version_variables_#{index}_source_config", "source_config (JSON)", class: label_class %>
+    <%= text_area_tag "version[variables][#{index}][source_config]",
+                      row["source_config"].presence && JSON.generate(row["source_config"]),
+                      rows: 2, spellcheck: false, id: "version_variables_#{index}_source_config",
+                      class: field_class("font-mono text-xs"),
+                      placeholder: '{"table": "federal_2026", "using": "salary"}' %>
+  </div>
+
+  <div class="flex items-end sm:col-span-2">
+    <label class="flex items-center gap-2 pb-2 text-sm text-slate-700">
+      <%# The hidden field is what makes an unchecked box post "0" instead of nothing;
+          `CastVariableRows` is what turns that "0" into a real `false`, which matters because
+          the core gem treats anything that is not literally `false` as required. %>
+      <%= hidden_field_tag "version[variables][#{index}][required]", "0", id: nil %>
+      <%= check_box_tag "version[variables][#{index}][required]", "1", row.fetch("required", true),
+                        id: "version_variables_#{index}_required",
+                        class: "rounded border-slate-300" %>
+      Required
+    </label>
+  </div>
+</fieldset>

data/app/views/acts_as_calculator_editor/formula_versions/index.html.erb

@@ -0,0 +1,45 @@
+<% content_for :title, "Versions of #{@formula.key}" %>
+
+<%= render "acts_as_calculator_editor/shared/page_header",
+           back_label: "← #{@formula.key}", back_path: formula_path(@formula),
+           title: "Versions of #{@formula.key}",
+           subtitle: "Scope: #{@formula.scope}",
+           actions: link_to("Publish new version", new_formula_version_path(@formula), class: button_class(:primary)) %>
+
+<div class="overflow-x-auto rounded-lg border border-slate-200 bg-white">
+  <table class="w-full text-sm">
+    <thead class="bg-slate-50 text-left text-xs uppercase tracking-wide text-slate-500">
+      <tr>
+        <th class="px-4 py-2 font-medium">#</th>
+        <th class="px-4 py-2 font-medium">Status</th>
+        <th class="px-4 py-2 font-medium">Effective</th>
+        <th class="px-4 py-2 font-medium">Expression</th>
+        <th class="px-4 py-2 font-medium">Variables</th>
+        <th class="px-4 py-2"></th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-slate-100">
+      <% @versions.each do |version| %>
+        <tr id="<%= dom_id(version) %>" class="hover:bg-slate-50">
+          <td class="px-4 py-2 text-slate-600"><%= version.version_number %></td>
+          <td class="px-4 py-2"><%= status_badge(version.status) %></td>
+          <td class="whitespace-nowrap px-4 py-2 font-mono text-xs text-slate-600">
+            <%= version.effective_from %> → <%= version.effective_to || "open" %>
+          </td>
+          <td class="px-4 py-2">
+            <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-xs text-slate-800"><%= version.expression %></code>
+          </td>
+          <td class="px-4 py-2 font-mono text-xs text-slate-600"><%= version.variables.map(&:name).sort.join(", ") %></td>
+          <td class="whitespace-nowrap px-4 py-2 text-right">
+            <%= link_to "Show", formula_version_path(@formula, version), class: "font-medium text-slate-700 hover:text-slate-900" %>
+            <%= link_to "Duplicate", new_formula_version_path(@formula, from_version_id: version.id), class: "ml-3 font-medium text-slate-700 hover:text-slate-900" %>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+
+  <% if @versions.empty? %>
+    <p class="px-4 py-3 text-sm text-slate-500">No versions yet.</p>
+  <% end %>
+</div>

data/app/views/acts_as_calculator_editor/formula_versions/new.html.erb

@@ -0,0 +1,80 @@
+<% content_for :title, "Publish a version of #{@formula.key}" %>
+
+<div class="mb-6">
+  <%= link_to "← #{@formula.key}", formula_path(@formula), class: "text-sm text-slate-500 hover:text-slate-900" %>
+  <h1 class="mt-1 text-2xl font-semibold tracking-tight">Publish a version of <%= @formula.key %></h1>
+  <p class="mt-1 text-sm text-slate-500">Scope: <code class="rounded bg-slate-100 px-1.5 py-0.5"><%= @formula.scope %></code></p>
+</div>
+
+<%= render "acts_as_calculator_editor/shared/error_message" %>
+
+<%# The overlap rule is knowable from data already in hand, so it is shown before submit
+    rather than discovered by a 409: no two active versions of one formula may cover
+    overlapping dates. %>
+<section class="active-ranges mb-6 rounded-lg border border-slate-200 bg-white p-4">
+  <h2 class="mb-2 text-sm font-semibold text-slate-900">Already in force</h2>
+  <% if @active_versions.empty? %>
+    <p class="text-sm text-slate-500">No active versions — any effective date is free.</p>
+  <% else %>
+    <ul class="mb-2 space-y-1 text-sm">
+      <% @active_versions.each do |version| %>
+        <li class="font-mono text-slate-700">
+          v<%= version.version_number %>: <%= version.effective_from %> → <%= version.effective_to || "open-ended" %>
+        </li>
+      <% end %>
+    </ul>
+    <p class="text-xs text-slate-500">Publishing an active version that starts inside one of these supersedes it. If that
+       would leave part of its range with no active version, the publish is refused and says
+       so.</p>
+  <% end %>
+</section>
+
+<%= form_with url: formula_versions_path(@formula), method: :post, scope: :version,
+              html: { class: "space-y-6" } do |form| %>
+  <div class="rounded-lg border border-slate-200 bg-white p-5">
+    <%= render "expression_field", value: @form["expression"] %>
+  </div>
+
+  <div class="grid gap-4 rounded-lg border border-slate-200 bg-white p-5 sm:grid-cols-2">
+    <div>
+      <%= form.label :effective_from, "Effective from", class: label_class %>
+      <%= form.date_field :effective_from, value: @form["effective_from"], required: true, class: field_class %>
+    </div>
+
+    <div>
+      <%= form.label :effective_to, "Effective to", class: label_class %>
+      <%= form.date_field :effective_to, value: @form["effective_to"], class: field_class %>
+      <span class="<%= hint_class %>">Blank = open-ended.</span>
+    </div>
+
+    <div>
+      <%= form.label :status, "Status", class: label_class %>
+      <%= form.select :status, ActsAsCalculator::FormulaVersion::STATUSES, { selected: @form["status"] }, class: field_class %>
+    </div>
+
+    <div>
+      <%= form.label :change_note, "Change note", class: label_class %>
+      <%= form.text_field :change_note, value: @form["change_note"], class: field_class,
+                          placeholder: "Why this version exists" %>
+    </div>
+  </div>
+
+  <div class="rounded-lg border border-slate-200 bg-white p-5">
+    <h2 class="text-sm font-semibold text-slate-900">Variables</h2>
+    <p class="mb-4 mt-1 text-xs text-slate-500">Every identifier the expression uses must be declared here, or the formula raises
+       MissingVariableError when it runs. Names here feed the expression editor's highlighting
+       and autocomplete as you type.</p>
+
+    <div class="space-y-3">
+      <% rows = @variable_rows + Array.new(3) { { "name" => "", "source_type" => "context" } } %>
+      <% rows.each_with_index do |row, index| %>
+        <%= render "variable_fields", index: index, row: row %>
+      <% end %>
+    </div>
+  </div>
+
+  <div class="flex items-center gap-3">
+    <%= form.submit "Publish version", class: button_class(:primary) %>
+    <%= link_to "Cancel", formula_path(@formula), class: button_class(:secondary) %>
+  </div>
+<% end %>

data/app/views/acts_as_calculator_editor/formula_versions/show.html.erb

@@ -0,0 +1,75 @@
+<% content_for :title, "#{@formula.key} v#{@version.version_number}" %>
+
+<%= render "acts_as_calculator_editor/shared/page_header",
+           back_label: "← #{@formula.key}", back_path: formula_path(@formula),
+           title: "#{@formula.key} — version #{@version.version_number}",
+           actions: link_to("Duplicate into a new version",
+                            new_formula_version_path(@formula, from_version_id: @version.id),
+                            class: button_class(:primary)) %>
+
+<%= render "acts_as_calculator_editor/shared/error_message" %>
+
+<section class="mb-8 rounded-lg border border-slate-200 bg-white p-5">
+  <dl class="grid gap-x-6 gap-y-4 sm:grid-cols-2">
+    <div>
+      <dt class="text-xs uppercase tracking-wide text-slate-500">Status</dt>
+      <dd class="mt-1"><%= status_badge(@version.status) %></dd>
+    </div>
+    <div>
+      <dt class="text-xs uppercase tracking-wide text-slate-500">Effective</dt>
+      <dd class="mt-1 font-mono text-sm text-slate-800">
+        <%= @version.effective_from %> → <%= @version.effective_to || "open-ended" %>
+      </dd>
+    </div>
+    <div class="sm:col-span-2">
+      <dt class="text-xs uppercase tracking-wide text-slate-500">Change note</dt>
+      <dd class="mt-1 text-sm text-slate-800"><%= @version.change_note.presence || "—" %></dd>
+    </div>
+    <div class="sm:col-span-2">
+      <dt class="text-xs uppercase tracking-wide text-slate-500">Expression</dt>
+      <dd class="mt-1">
+        <pre class="overflow-x-auto rounded-md bg-slate-900 p-3 font-mono text-xs text-slate-100"><code><%= @version.expression %></code></pre>
+      </dd>
+    </div>
+  </dl>
+</section>
+
+<section class="mb-8 overflow-x-auto rounded-lg border border-slate-200 bg-white">
+  <header class="border-b border-slate-200 px-4 py-3">
+    <h2 class="text-sm font-semibold text-slate-900">Variables</h2>
+  </header>
+  <table class="w-full text-sm">
+    <thead class="bg-slate-50 text-left text-xs uppercase tracking-wide text-slate-500">
+      <tr>
+        <th class="px-4 py-2 font-medium">Name</th>
+        <th class="px-4 py-2 font-medium">Source</th>
+        <th class="px-4 py-2 font-medium">Required</th>
+        <th class="px-4 py-2 font-medium">source_config</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-slate-100">
+      <% @variables.each do |variable| %>
+        <tr>
+          <td class="px-4 py-2 font-mono font-medium text-slate-900"><%= variable.name %></td>
+          <td class="px-4 py-2 text-slate-600"><%= variable.source_type %></td>
+          <td class="px-4 py-2 text-slate-600"><%= variable.required? %></td>
+          <td class="px-4 py-2">
+            <code class="rounded bg-slate-100 px-1.5 py-0.5 font-mono text-xs text-slate-800"><%= JSON.generate(variable.source_config || {}) %></code>
+          </td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+
+  <% if @variables.empty? %>
+    <p class="px-4 py-3 text-sm text-slate-500">No variables declared.</p>
+  <% end %>
+</section>
+
+<%# No edit form, by design: `expression`, `effective_from` and `version_number` are
+    immutable once a version is active. Publishing a corrected version is the fix; the bad
+    one stays in the history where the audit trail expects it. %>
+<p class="rounded-md border border-slate-200 bg-slate-100 px-4 py-3 text-sm text-slate-600">
+  Versions are immutable. To correct this one, duplicate it into a new version — the original
+  stays in the history the audit trail depends on.
+</p>

data/app/views/acts_as_calculator_editor/formulas/_form.html.erb

@@ -0,0 +1,23 @@
+<%# Identity only. There is deliberately no `expression` field here — a formula's maths
+    lives on its versions, and this form would be the wrong place to imply otherwise.
+    There is no owner field either; see ActsAsCalculatorEditor.owner_classes. %>
+<%= form_with url: url, method: http_method, scope: :formula, html: { class: "space-y-6" } do |form| %>
+  <div class="grid gap-4 rounded-lg border border-slate-200 bg-white p-5 sm:grid-cols-2">
+    <div>
+      <%= form.label :key, "Key", class: label_class %>
+      <%= form.text_field :key, value: formula.key, required: true, class: field_class("font-mono") %>
+    </div>
+
+    <div>
+      <%= form.label :scope, "Scope", class: label_class %>
+      <%= form.text_field :scope, value: formula.scope, class: field_class("font-mono"),
+                          placeholder: ActsAsCalculator::DEFAULT_SCOPE %>
+      <span class="<%= hint_class %>">Uniqueness is [key, scope, owner] — two formulas may share a key in different scopes.</span>
+    </div>
+  </div>
+
+  <div class="flex items-center gap-3">
+    <%= form.submit submit_label, class: button_class(:primary) %>
+    <%= link_to "Cancel", cancel_path, class: button_class(:secondary) %>
+  </div>
+<% end %>

data/app/views/acts_as_calculator_editor/formulas/edit.html.erb

@@ -0,0 +1,11 @@
+<% content_for :title, "Edit formula" %>
+
+<%= render "acts_as_calculator_editor/shared/page_header",
+           back_label: "← #{@formula.key}", back_path: formula_path(@formula),
+           title: "Edit #{@formula.key}",
+           subtitle: "Identity only: renaming or re-scoping silently re-targets every future calculation of that key, so this form changes nothing about its maths." %>
+
+<%= render "acts_as_calculator_editor/shared/error_message" %>
+
+<%= render "form", formula: @formula, url: formula_path(@formula), http_method: :patch,
+                   submit_label: "Save formula", cancel_path: formula_path(@formula) %>