acts_as_calculator 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c4c2ae76d289d7d038706eaace2037b440d0043375970acbe19e10df2aef610
-  data.tar.gz: 5785e9931c5bee714ab33c56c1d3f6fb1f7e2fbf866e5bb2534a59c49d0fe678
+  metadata.gz: 6ad149828fc403a8faf199be49400d0f5742df5d131fee9c45d61dd4aa961477
+  data.tar.gz: 7a24e2b53e7b408e597d1e08c3eda46b03d61b3c26ceb4b7f9c27f9ca7f6814a
 SHA512:
-  metadata.gz: f3758535be10ef2eb3cbc481232a5450be2ff2223ad0ea89eb0c7eca34ca09a4673fbe16a77df16fcc04fdab031aa8022a3f5bec8a6e3c503d455cd4cd7dc8a6
-  data.tar.gz: 62e82cdda250fc79160066529fcedbecb5e49d6032a3731a48e958131197bcdcdb0fbf7ab96227d3a0de64d29abe55cf877247023d7c73ff95fb9c432a2b6a39
+  metadata.gz: ccf113444d6697e1be4ffa9e05642cbff4c0846720d1c884360a13ec480d97842d43bd96ffb99199c7e99ce58d9f099628ee678bb34831058da3ebcbaf5b3cfc
+  data.tar.gz: 76fec437da064bbf0d9ebc5f45d51992e4c82721e635a82a79851b2a9301db3f2b2873b902a4ad511af0cbecbde420d3375173220c854db50414e9c098a85584

data/.rubocop.yml

@@ -3,14 +3,9 @@ AllCops:
   NewCops: disable
   SuggestExtensions: false
 
-# Decrees are invoked as `DoSomething.(...)` at call sites but delegate with an explicit
-# `new(...).call` — see the decree-service-objects skill. Neither style is wrong here.
 Style/LambdaCall:
   Enabled: false
 
-# Decrees take keyword arguments by design (docs/PLAN.md, "Code guidelines"), and a
-# keyword argument costs a reader nothing at the call site — counting them would turn the
-# gem's mandated style into an offence. Positional parameters are still capped.
 Metrics/ParameterLists:
   CountKeywordArgs: false
 

data/README.md

@@ -1,43 +1,152 @@
 # ActsAsCalculator
 
-A pricing and calculation engine built on [Dentaku](https://github.com/rubysolo/dentaku). Mix `Calculable` into any model to get effective-dated, versioned formulas; apportionment and aggregation helpers; and Liquid-rendered output — reusable across payroll, e-commerce, and insurance domains.
+A calculation engine for pricing, payroll, tax, and insurance domains. Built on [Dentaku](https://github.com/rubysolo/dentaku).
 
-This gem is under active development. See the [architecture plan](https://claude.ai/code/artifact/b02e27b6-eb9c-4b8d-8037-ef69f177c282) for the full design: data model, calculation flow, extensibility points, and build order.
+Add formula-based calculations to any model with `Calculable`. Formulas are versioned, effective-dated, can call other formulas, and render to Liquid templates.
 
-## Installation
+## Install
 
-Not yet released to RubyGems. Once published:
+```ruby
+bundle add acts_as_calculator
+rails generate acts_as_calculator:install
+rails db:migrate
+```
+
+## Quick Start
+
+Mix `Calculable` into your model:
+
+```ruby
+class Employee < ApplicationRecord
+  include ActsAsCalculator::Calculable
+end
+```
+
+Create a formula:
+
+```ruby
+ActsAsCalculator::Formula.create!(key: "net_pay", scope: "payroll")
+formula = ActsAsCalculator::Formula.find_by(key: "net_pay")
+
+formula.versions.create!(
+  expression: "gross - tax - deductions",
+  effective_from: Date.new(2026, 1, 1),
+  effective_to: nil,
+  status: "active",
+  variables: [
+    { name: "gross", source_type: "attribute" },
+    { name: "tax", source_type: "context" },
+    { name: "deductions", source_type: "context" }
+  ]
+)
+```
+
+Calculate:
+
+```ruby
+employee = Employee.find(1)
+
+result = employee.calculate(
+  :net_pay,
+  as_of: Date.new(2026, 3, 15),
+  tax: BigDecimal("500"),
+  deductions: BigDecimal("200")
+)
+
+result.value          # => #<BigDecimal "2300.00">
+result.breakdown      # => { expression: "...", inputs: {...}, calls: [...] }
+```
+
+## Formulas Calling Formulas
+
+Use `@formula_key` syntax to call other formulas:
+
+```ruby
+formula = ActsAsCalculator::Formula.create!(key: "total_deductions", scope: "payroll")
+
+formula.versions.create!(
+  expression: "@tax + @insurance + @retirement",
+  effective_from: Date.new(2026, 1, 1),
+  status: "active",
+  variables: [
+    { name: "salary", source_type: "attribute" }
+  ],
+  formula_calls: [
+    { key: "tax" },
+    { key: "insurance" },
+    { key: "retirement" }
+  ]
+)
+```
+
+Each called formula resolves independently at the calculation date. Pin a specific version:
+
+```ruby
+formula_calls: [
+  { key: "tax", version_id: 2 }  # Always use version 2, ignore as_of
+]
+```
+
+## Lookup Tables
+
+Use lookup tables for tiered calculations:
+
+```ruby
+table = ActsAsCalculator::LookupTable.create!(key: "tax_brackets", scope: "payroll")
+
+table.entries.create!([
+  { from: 0, to: 20000, value: BigDecimal("0.10") },
+  { from: 20000, to: 50000, value: BigDecimal("0.22") },
+  { from: 50000, to: nil, value: BigDecimal("0.32") }
+])
+```
+
+Reference in formulas:
 
-    $ bundle add acts_as_calculator
+```ruby
+formula.versions.create!(
+  expression: "salary * bracket",
+  variables: [
+    { name: "salary", source_type: "attribute" },
+    { name: "bracket", source_type: "lookup",
+      source_config: { table: "tax_brackets", using: "salary" } }
+  ]
+)
+```
 
-## JSON import
+## Templates
+
+Render results to Liquid templates:
+
+```ruby
+ActsAsCalculator::Template.create!(
+  key: "payslip",
+  scope: "payroll",
+  format: "text",
+  body: "Net: {{ result.value | currency }}"
+)
+
+rendered = employee.render(:payslip, as_of: Date.today, net_pay: result.value)
+```
 
-Formulas, lookup tables and templates can be authored as JSON and imported either once
-through a generator or repeatedly from a deploy script:
+Available filters: `currency`, `percentage`, `date`.
 
-    $ rails generate acts_as_calculator:import config/calculator/payroll.json
-    $ rake acts_as_calculator:import[config/calculator/payroll.json]
+## JSON Import
 
-Both run the same code and print the same created/updated/skipped/failed summary; the rake
-task exits non-zero if any entry failed. One file may declare any of the three sections.
+Define formulas, lookup tables, and templates in JSON:
 
 ```json
 {
   "lookup_tables": [
-    { "key": "federal_2026", "scope": "payroll",
-      "entries": [{ "from": 0, "to": 20000, "value": 0.1 },
-                  { "from": 20000, "to": null, "value": 0.25 }] }
+    { "key": "tax_brackets", "scope": "payroll",
+      "entries": [{ "from": 0, "to": 20000, "value": 0.1 }] }
   ],
   "formulas": [
     { "key": "net_pay", "scope": "payroll",
-      "expression": "salary - (salary * federal_2026)",
-      "effective_from": "2026-01-01", "effective_to": null,
-      "status": "active", "change_note": "2026 rates",
-      "variables": [
-        { "name": "salary", "source_type": "attribute" },
-        { "name": "federal_2026", "source_type": "lookup",
-          "source_config": { "table": "federal_2026", "using": "salary" } }
-      ] }
+      "expression": "salary - tax",
+      "effective_from": "2026-01-01",
+      "status": "active",
+      "variables": [{ "name": "salary", "source_type": "attribute" }] }
   ],
   "templates": [
     { "key": "payslip", "scope": "payroll", "format": "text",
@@ -46,32 +155,18 @@ task exits non-zero if any entry failed. One file may declare any of the three s
 }
 ```
 
-`scope` defaults to `"default"`, a formula's `status` to `"active"`, a template's `format`
-to `"html"`, and a variable's `source_type` to `"context"` and `required` to `true`. Any
-entry may carry `"owner": { "type": "Company", "id": 7 }` to import into a tenant-scoped
-row instead of the global one.
-
-Importing is idempotent, keyed on `[key, scope, owner]`:
-
-- **Formulas** — re-importing unchanged content is a no-op. Changed content adds a *new*
-  version; existing versions are never edited. Publishing an active version closes out or
-  retires the one it supersedes, but never rewrites its expression — and it is refused
-  outright if superseding would leave part of the incumbent's range with no active version,
-  rather than silently deleting coverage a past calculation relied on. Extend the new
-  version's `effective_to`, or declare the version taking over the tail earlier in the file.
-- **Lookup tables** — unchanged entries are a no-op, and changed entries are replaced in
-  place *only* if no active or retired formula version resolves to that table. If one does,
-  the import fails that entry rather than retroactively changing what an audited
-  calculation was measured against; author a new table key and a new formula version
-  pointing at it.
-- **Templates** — unchanged body and format are a no-op; a change publishes a new version
-  and demotes the previous one, which stays in the history for rollback.
-
-## The API
-
-The gem ships a mountable REST/JSON API that is **off by default** — not guarded, off. The
-routes are behind a routing constraint, so with `enable_api` false they do not match at
-all: requests 404 because there is no such path, not because a controller declined.
+Import once or repeatedly:
+
+```bash
+rails generate acts_as_calculator:import config/payroll.json
+rake acts_as_calculator:import[config/payroll.json]
+```
+
+Both run the same logic and report created/updated/skipped counts. Importing is idempotent — unchanged content is skipped, changed content creates a new version.
+
+## API
+
+Enable the REST/JSON API (disabled by default):
 
 ```ruby
 # config/initializers/acts_as_calculator.rb
@@ -81,53 +176,12 @@ ActsAsCalculator.configure { |c| c.enable_api = true }
 mount ActsAsCalculator::Engine => "/calculator"
 ```
 
-The gem implements **no authentication or authorization** and never will — wrap the mount
-point in whatever your app already uses.
-
-| Method | Path | What it does |
-|---|---|---|
-| `GET` | `/formulas` | Identity only (`key`, `scope`, `owner`); filter with `?key=&scope=` |
-| `POST` | `/formulas` | Creates a formula identity |
-| `GET` | `/formulas/:id` | The formula plus its version history |
-| `PATCH` | `/formulas/:id` | Updates only the identity attributes that were sent — including `owner`, unguarded; re-owning a formula silently re-targets every future `#calculate` resolution for that key, it isn't a rename-only endpoint |
-| `DELETE` | `/formulas/:id` | 409s instead of deleting a formula whose versions have runs |
-| `GET` | `/formulas/:id/versions` | Versions in version order |
-| `GET` | `/formulas/:id/versions/:id` | One version with its declared variables |
-| `POST` | `/formulas/:id/versions` | Publishes a version and its variables |
-| `GET` | `/templates` | Every version; `?current=true` narrows to the published one |
-| `POST` | `/templates` | Publishes a new version and demotes the outgoing one |
-| `GET`/`DELETE` | `/templates/:id` | |
-| `POST` | `/templates/:id/preview` | Renders against a posted `context` → `{ body:, format: }` |
-| `POST` | `/templates/:id/promote` | Rollback — points `current` at this version |
-| `POST` | `/import` | The JSON import document above, over HTTP |
-
-Writes go through the same Decrees the other authoring paths use, so the API is not a way
-around the rules: publishing a version supersedes the one in force rather than overlapping
-it, and a supersede that would leave part of the incumbent's range with no active version
-comes back as `409 Conflict` rather than silently creating a gap. `POST /import` is
-`ImportDefinitions` handed the parsed body — same idempotency, same lookup-table guard, and
-the same per-entry created/updated/skipped/failed summary the rake task prints, as JSON.
-
-Errors are `{ "error": { "type": ..., "message": ..., "details": {...} } }`: 422 on
-validation failure (with the model's own messages), 404 on a record or template that isn't
-there, 409 on a conflict with existing state, 400 on a malformed request body.
-
-Lookup tables have no CRUD endpoints of their own. `docs/PLAN.md` names formulas, versions
-and templates as the API's surface, and lookup tables are already authorable over HTTP
-through `POST /import` — which is also the only path that enforces the guard against
-editing a table an audited formula version resolves to.
-
-## Development
-
-    $ bin/setup
-    $ rake spec
-
-`bin/console` gives an interactive prompt for experimenting.
+Endpoints: `GET/POST /formulas`, `GET/PATCH/DELETE /formulas/:id`, `GET/POST /formulas/:id/versions`, `GET/POST /templates`, `GET/DELETE /templates/:id`, `POST /templates/:id/preview`, `POST /import`.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/lautarograc/acts_as_calculator. This project follows the [code of conduct](https://github.com/lautarograc/acts_as_calculator/blob/main/CODE_OF_CONDUCT.md).
+Issues and PRs welcome at https://github.com/lautarograc/acts_as_calculator.
 
 ## License
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+MIT

data/app/controllers/acts_as_calculator/application_controller.rb

@@ -1,13 +1,7 @@
 # frozen_string_literal: true
 
 module ActsAsCalculator
-  # There is deliberately no authentication or authorization here, and no `before_action`
-  # stub inviting one (docs/PLAN.md, "Constraints & non-goals"). The gem's only gate is the
-  # routing constraint in config/routes.rb; a host that opts the API on wraps the mounted
-  # engine in its own auth, at its own mount point.
   class ApplicationController < ActionController::API
-    # rescue_from matches the most recently registered handler first, so the catch-all for
-    # the gem's own errors goes first and the narrower ones override it below.
     rescue_from Error, with: :render_unprocessable
     rescue_from FormulaNotFoundError, TemplateNotFoundError, NoEffectiveVersionError, with: :render_not_found
     rescue_from PartialSupersedeError, with: :render_conflict
@@ -37,8 +31,6 @@ module ActsAsCalculator
       render_error(error, :bad_request)
     end
 
-    # 409, not 422: the request is well-formed and the state is valid — the two are just
-    # irreconcilable without the operator saying which range they meant to keep.
     def render_conflict(error)
       render_error(error, :conflict)
     end
@@ -47,28 +39,20 @@ module ActsAsCalculator
       render_error(error, :unprocessable_entity, details: error.record.errors.messages)
     end
 
-    # Reached when a version still has runs: the audit trail is never deleted to make room
-    # for a delete of something else (docs/PLAN.md, "Data model").
     def render_record_not_destroyed(error)
       render_error(error, :conflict, details: error.record.errors.messages)
     end
 
-    # Nested params arrive as ActionController::Parameters, which is not a Hash — anything
-    # handed to a Decree has to be a plain one first.
     def plain_hash(value)
       value.respond_to?(:to_unsafe_h) ? value.to_unsafe_h.to_h : (value || {}).to_h
     end
 
-    # `key` alone never identifies a row in this gem (docs/PLAN.md, "Data model"), so an
-    # index filters on the pair.
     def filter_by_key_and_scope(relation)
       relation = relation.where(key: params[:key]) if params[:key].present?
       relation = relation.where(scope: params[:scope]) if params[:scope].present?
       relation
     end
 
-    # `{"type": "Company", "id": 7}` — the same owner reference the JSON import takes, run
-    # through the same guard that refuses a type which isn't an ActiveRecord model.
     def resolve_owner(reference)
       ResolveImportOwner.(plain_hash(reference).presence)
     end

data/app/controllers/acts_as_calculator/formula_versions_controller.rb

@@ -12,10 +12,6 @@ module ActsAsCalculator
       render json: { version: SerializeFormulaVersion.(version:, variables: true) }
     end
 
-    # Straight through `PublishFormulaVersion`, so the API takes exactly the same route
-    # through the effective-dating rules as the JSON import does: the incumbent is
-    # superseded, never rewritten, and a supersede that would leave part of its range with
-    # no active version raises `PartialSupersedeError` — surfaced as a 409, not swallowed.
     def create
       published = PublishFormulaVersion.(formula:, **version_attributes)
 

data/app/controllers/acts_as_calculator/formulas_controller.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module ActsAsCalculator
-  # Identity only — `key`, `scope`, `owner`. Everything that can change about a formula is
-  # a version, which is why there is a separate controller for those.
   class FormulasController < ApplicationController
     def index
       render json: { formulas: scoped_formulas.map { |formula| SerializeFormula.(formula:) } }
@@ -44,8 +42,6 @@ module ActsAsCalculator
       params.require(:formula).permit(:key, :scope, owner: %i[type id])
     end
 
-    # Only what was sent, so a PATCH that renames a formula doesn't blank its scope. `scope`
-    # is left to the column default on create rather than defaulted here.
     def formula_attributes
       permitted = formula_params
       attributes = {}

data/app/controllers/acts_as_calculator/imports_controller.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
 module ActsAsCalculator
-  # docs/PLAN.md lists JSON import and the API as two authoring paths, not two import
-  # mechanisms: this is `ImportDefinitions` handed the parsed request body, so an HTTP
-  # import means exactly what the generator and the rake task mean, idempotency and
-  # lookup-table guard included.
   class ImportsController < ApplicationController
     def create
       summary = ImportDefinitions.(data: definitions)
@@ -15,11 +11,6 @@ module ActsAsCalculator
 
     private
 
-    # The request body itself, not `params` — which carries `controller` and `action`, and
-    # `ImportDefinitions` rejects a section it doesn't recognise rather than ignoring it.
-    #
-    # An empty document is refused for the same reason a misspelled section is: reporting
-    # "0 created, 0 failed" to a caller whose body never parsed looks exactly like success.
     def definitions
       body = request.request_parameters
       if body.empty?

data/app/controllers/acts_as_calculator/templates_controller.rb

@@ -22,16 +22,12 @@ module ActsAsCalculator
       head :no_content
     end
 
-    # `{ body:, format: }`, never `html_safe` — whether API-authored markup is safe to
-    # inject into a page is the host's call, not this gem's (Phase 3).
     def preview
       body = RenderTemplate.(template:, context: plain_hash(params[:context]))
 
       render json: { preview: { body:, format: template.format } }
     end
 
-    # Rollback: point `current` at an older version instead of deleting the one that went
-    # wrong, which is the whole reason the version history exists.
     def promote
       render json: { template: SerializeTemplate.(template: PromoteTemplate.(template:)) }
     end
@@ -47,8 +43,6 @@ module ActsAsCalculator
       current_only? ? templates.current : templates
     end
 
-    # Spelled out rather than reaching for ActiveModel::Type::Boolean, which the gemspec
-    # doesn't declare and which is more machinery than one query parameter is worth.
     def current_only?
       %w[true 1].include?(params[:current].to_s)
     end

data/app/models/acts_as_calculator/formula_version.rb

@@ -9,8 +9,6 @@ module ActsAsCalculator
     RETIRED = "retired"
     STATUSES = [DRAFT, ACTIVE, RETIRED].freeze
 
-    # `effective_to` and `status` stay writable so an active version can be closed out or
-    # retired; rewriting what was in force on a date already calculated is what's banned.
     IMMUTABLE_ONCE_ACTIVE = %w[formula_id version_number expression effective_from].freeze
 
     belongs_to :formula, inverse_of: :versions

data/app/models/acts_as_calculator/lookup_table_entry.rb

@@ -10,9 +10,6 @@ module ActsAsCalculator
     validates :position, presence: true, numericality: { only_integer: true }
     validate :bounds_ordered
 
-    # `from`/`to` are half-open and nullable on both ends, so neither is orderable in SQL
-    # in a way that puts an unbounded floor first across every adapter — position is the
-    # explicit, adapter-independent answer.
     scope :ordered, -> { order(:position, :id) }
 
     private

data/app/models/acts_as_calculator/record.rb

@@ -4,9 +4,6 @@ module ActsAsCalculator
   class Record < ::ActiveRecord::Base
     self.abstract_class = true
 
-    # Set here rather than inherited from the host: `belongs_to_required_by_default` only
-    # becomes true via `config.load_defaults`, and whether a run may be saved without the
-    # formula version it applied is not the host's decision to make.
     self.belongs_to_required_by_default = true
   end
 end

data/app/models/acts_as_calculator/run.rb

@@ -15,8 +15,6 @@ module ActsAsCalculator
       joins(formula_version: :formula).where(calculator_formulas: { key: key.to_s })
     }
 
-    # The audit trail is append-only: a correction is a new run, never an edit of the row
-    # that recorded what was actually applied.
     def readonly?
       persisted?
     end

data/app/models/acts_as_calculator/template.rb

@@ -16,8 +16,6 @@ module ActsAsCalculator
     validates :format, inclusion: { in: FORMATS }
     validates :version_number, presence: true, numericality: { only_integer: true, greater_than: 0 }
 
-    # Only on update: a create demotes its siblings in before_create, which runs *after*
-    # validation, so running this on create would flag the version it is about to replace.
     validate :single_current_version, on: :update
 
     before_create :demote_other_versions, if: :current?

data/config/routes.rb

@@ -1,27 +1,11 @@
 # frozen_string_literal: true
 
-# The API ships off (docs/PLAN.md, "Authoring paths"): a host opts in with
-# `ActsAsCalculator.configure { |c| c.enable_api = true }`.
-#
-# The gate is a routing constraint rather than a `before_action` on purpose. A controller
-# guard leaves the route registered — the router matches it, instantiates the controller,
-# and the controller declines — which means the endpoints exist, answer HEAD/OPTIONS, show
-# up in `rails routes`, and are one forgotten `skip_before_action` away from being live.
-# A constraint that returns false makes the route not match at all: the engine's router
-# passes, the host's router finds nothing, and the request 404s because there is no such
-# path. Off means absent, not refused.
-#
-# The lambda is evaluated per request, so the flag is read at match time, not captured when
-# the routes were drawn.
 ActsAsCalculator::Engine.routes.draw do
   constraints(->(_request) { ActsAsCalculator.configuration.enable_api }) do
     resources :formulas, only: %i[index show create update destroy] do
       resources :versions, only: %i[index show create], controller: "formula_versions"
     end
 
-    # No `update`: a template body is versioned for rollback, so a change publishes a new
-    # version (POST) and going back promotes an old one — editing a row in place would
-    # rewrite the history that makes rollback possible.
     resources :templates, only: %i[index show create destroy] do
       member do
         post :preview
@@ -29,8 +13,6 @@ ActsAsCalculator::Engine.routes.draw do
       end
     end
 
-    # docs/PLAN.md's JSON import, reachable over HTTP — the same ImportDefinitions the
-    # generator and the rake task call, handed a parsed body instead of a file.
     post "import", to: "imports#create"
   end
 end

data/lib/acts_as_calculator/calculable.rb

@@ -8,8 +8,6 @@ module ActsAsCalculator
     extend ::ActiveSupport::Concern
 
     included do
-      # No `dependent:` on purpose. Whether an audit trail outlives the record it audited
-      # is the host app's retention policy, and Run#readonly? makes `:destroy` raise.
       has_many :calculator_runs,
                class_name: "ActsAsCalculator::Run",
                as: :calculable,
@@ -24,9 +22,6 @@ module ActsAsCalculator
       end
     end
 
-    # Leftover keywords splat into the calculation context, which makes `as_of`, `scope`,
-    # `owner` and `dry_run` unusable as Dentaku variable names; `context:` is the escape
-    # hatch for a formula that genuinely declares one, and wins over the splat.
     def calculate(key, as_of: nil, scope: nil, owner: nil, dry_run: false, context: {}, **extra)
       EvaluateFormula.(
         calculable: self,
@@ -53,10 +48,6 @@ module ActsAsCalculator
       nil
     end
 
-    # Chains a calculation and a render in one call — `calculate:` names one formula key
-    # (assigned as `result`) or several (assigned as `results`) — or renders a Result the
-    # caller already has. Leftover keywords splat into the template's assigns *and* into
-    # the calculation's context, so one call can feed both.
     def render(key, calculate: nil, result: nil, results: {}, as_of: nil, scope: nil,
                owner: nil, version_number: nil, dry_run: false, context: {}, **extra)
       assigns = extra.merge(context)
@@ -73,8 +64,6 @@ module ActsAsCalculator
 
     private
 
-    # Forwards the assigns as `context:` rather than splatting them, so a key named
-    # `scope` reaches the formula instead of redirecting its lookup.
     def calculator_render_results(keys, as_of:, scope:, owner:, dry_run:, context:)
       Array(keys).to_h do |formula_key|
         [formula_key.to_s, calculate(formula_key, as_of:, scope:, owner:, dry_run:, context:)]

data/lib/acts_as_calculator/calculator_cache.rb

@@ -25,10 +25,6 @@ module ActsAsCalculator
 
     attr_reader :functions, :key
 
-    # Keyed by formula_version_id because version content is immutable, so an entry can
-    # never go stale. Held per thread because Dentaku::Calculator mutates its own memory
-    # while evaluating — one shared instance across a Puma thread pool would interleave
-    # two requests' variables.
     def store
       Thread.current[key] ||= {}
     end

data/lib/acts_as_calculator/cast_json_safe.rb

@@ -9,8 +9,6 @@ module ActsAsCalculator
     def self.call(value)
       case value
       when Hash, Array then container(value)
-      # BigDecimal#to_json emits "0.1234e4"; a plain decimal string round-trips into the
-      # jsonb column as something a human (and a Phase 3 template) can read.
       when BigDecimal then value.to_s("F")
       when Symbol then value.to_s
       when Rational then value.to_f

data/lib/acts_as_calculator/cast_liquid_value.rb

@@ -5,10 +5,6 @@ require "date"
 require "liquid"
 
 module ActsAsCalculator
-  # The one gate into a template's render context. Liquid only dispatches methods on
-  # `Liquid::Drop`s and hash-likes, so the sandbox holds exactly as long as nothing else
-  # is assigned — an allowlist here is what makes that a property of the code rather than
-  # a habit every caller has to remember.
   class CastLiquidValue
     PASS_THROUGH = [
       ::NilClass, ::TrueClass, ::FalseClass, ::String, ::Integer, ::Float,
@@ -27,18 +23,12 @@ module ActsAsCalculator
     def self.scalar(value)
       return value if PASS_THROUGH.any? { |type| value.is_a?(type) }
       return value.to_s if value.is_a?(::Symbol)
-      # BigDecimal#to_s emits engineering notation ("0.1e4"), which is not what belongs in
-      # rendered output; the plain-decimal form round-trips exactly back through CastDecimal.
       return value.to_s("F") if value.is_a?(::BigDecimal)
 
       time_like(value) || refuse(value)
     end
     private_class_method :scalar
 
-    # The one class a Rails host will hit that is neither a Date nor a Time, since
-    # `record.created_at` is the obvious thing to pass. Matched by name because the core
-    # layer must stay loadable without ActiveSupport, and named rather than duck-typed so
-    # this stays an allowlist — `respond_to?(:strftime)` would admit anything.
     TIME_WITH_ZONE = "ActiveSupport::TimeWithZone"
 
     # rubocop:disable Style/ClassEqualityComparison -- instance_of? would need the constant

data/lib/acts_as_calculator/cast_variable_attributes.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
 module ActsAsCalculator
-  # Both authoring paths hand over the same loose variable declaration — an import file's
-  # `variables` list and the API's — and both have to land on the same row, with the same
-  # defaults. Keeping the defaulting here is what stops the two from drifting.
   class CastVariableAttributes
     def self.call(variable)
       variable = variable.to_h.transform_keys(&:to_s)

data/lib/acts_as_calculator/configuration.rb

@@ -1,13 +1,6 @@
 # frozen_string_literal: true
 
 module ActsAsCalculator
-  # Host-facing settings, set from an initializer:
-  #
-  #   ActsAsCalculator.configure { |c| c.enable_api = true }
-  #
-  # `enable_api` is read per request by the routing constraint in `config/routes.rb`, not
-  # captured when the routes are drawn — so flipping it takes effect without a reload, and
-  # a host can gate the API on something it computes at boot.
   class Configuration
     attr_accessor :enable_api
 
@@ -24,7 +17,6 @@ module ActsAsCalculator
     yield(configuration)
   end
 
-  # Test-suite affordance: a host's own specs need to flip `enable_api` and put it back.
   def self.reset_configuration!
     @configuration = Configuration.new
   end