acts_as_calculator 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c4c2ae76d289d7d038706eaace2037b440d0043375970acbe19e10df2aef610
+  data.tar.gz: 5785e9931c5bee714ab33c56c1d3f6fb1f7e2fbf866e5bb2534a59c49d0fe678
+SHA512:
+  metadata.gz: f3758535be10ef2eb3cbc481232a5450be2ff2223ad0ea89eb0c7eca34ca09a4673fbe16a77df16fcc04fdab031aa8022a3f5bec8a6e3c503d455cd4cd7dc8a6
+  data.tar.gz: 62e82cdda250fc79160066529fcedbecb5e49d6032a3731a48e958131197bcdcdb0fbf7ab96227d3a0de64d29abe55cf877247023d7c73ff95fb9c432a2b6a39

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,38 @@
+AllCops:
+  TargetRubyVersion: 3.2
+  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
+
+Metrics/BlockLength:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "spec/**/*"
+
+Naming/VariableNumber:
+  inherit_mode:
+    merge:
+      - Exclude
+  Exclude:
+    - "spec/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 lautarograc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,133 @@
+# 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.
+
+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.
+
+## Installation
+
+Not yet released to RubyGems. Once published:
+
+    $ bundle add acts_as_calculator
+
+## JSON import
+
+Formulas, lookup tables and templates can be authored as JSON and imported either once
+through a generator or repeatedly from a deploy script:
+
+    $ rails generate acts_as_calculator:import config/calculator/payroll.json
+    $ rake acts_as_calculator:import[config/calculator/payroll.json]
+
+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.
+
+```json
+{
+  "lookup_tables": [
+    { "key": "federal_2026", "scope": "payroll",
+      "entries": [{ "from": 0, "to": 20000, "value": 0.1 },
+                  { "from": 20000, "to": null, "value": 0.25 }] }
+  ],
+  "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" } }
+      ] }
+  ],
+  "templates": [
+    { "key": "payslip", "scope": "payroll", "format": "text",
+      "body": "Net: {{ result.value | currency }}" }
+  ]
+}
+```
+
+`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.
+
+```ruby
+# config/initializers/acts_as_calculator.rb
+ActsAsCalculator.configure { |c| c.enable_api = true }
+
+# config/routes.rb
+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.
+
+## 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).
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/app/controllers/acts_as_calculator/application_controller.rb

@@ -0,0 +1,76 @@
+# 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
+    rescue_from ::ActiveRecord::RecordNotFound, with: :render_not_found
+    rescue_from ::ActiveRecord::RecordInvalid, with: :render_record_invalid
+    rescue_from ::ActiveRecord::RecordNotDestroyed, with: :render_record_not_destroyed
+    rescue_from ::ActionController::ParameterMissing, with: :render_bad_request
+
+    private
+
+    def render_error(error, status, details: nil)
+      payload = { type: error.class.name, message: error.message }
+      payload[:details] = details if details
+
+      render json: { error: payload }, status:
+    end
+
+    def render_unprocessable(error)
+      render_error(error, :unprocessable_entity)
+    end
+
+    def render_not_found(error)
+      render_error(error, :not_found)
+    end
+
+    def render_bad_request(error)
+      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
+
+    def render_record_invalid(error)
+      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
+  end
+end

data/app/controllers/acts_as_calculator/formula_versions_controller.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class FormulaVersionsController < ApplicationController
+    def index
+      versions = formula.versions.order(:version_number)
+
+      render json: { versions: versions.map { |version| SerializeFormulaVersion.(version:) } }
+    end
+
+    def show
+      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)
+
+      render json: { version: SerializeFormulaVersion.(version: published, variables: true) },
+             status: :created
+    end
+
+    private
+
+    def formula
+      @formula ||= Formula.find(params[:formula_id])
+    end
+
+    def version
+      @version ||= formula.versions.find(params[:id])
+    end
+
+    def version_attributes
+      permitted = params.require(:version).permit(
+        :expression, :effective_from, :effective_to, :status, :change_note,
+        variables: [:name, :source_type, :required, { source_config: {} }]
+      )
+
+      { expression: permitted[:expression],
+        effective_from: permitted[:effective_from],
+        effective_to: permitted[:effective_to].presence,
+        status: permitted[:status].presence || FormulaVersion::ACTIVE,
+        change_note: permitted[:change_note],
+        variables: Array(permitted[:variables]).map { |variable| plain_hash(variable) } }
+    end
+  end
+end

data/app/controllers/acts_as_calculator/formulas_controller.rb

@@ -0,0 +1,58 @@
+# 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:) } }
+    end
+
+    def show
+      render json: { formula: SerializeFormula.(formula:, versions: true) }
+    end
+
+    def create
+      created = Formula.create!(**formula_attributes)
+
+      render json: { formula: SerializeFormula.(formula: created) }, status: :created
+    end
+
+    def update
+      formula.update!(**formula_attributes)
+
+      render json: { formula: SerializeFormula.(formula:) }
+    end
+
+    def destroy
+      formula.destroy!
+
+      head :no_content
+    end
+
+    private
+
+    def formula
+      @formula ||= Formula.find(params[:id])
+    end
+
+    def scoped_formulas
+      filter_by_key_and_scope(Formula.order(:scope, :key, :id))
+    end
+
+    def formula_params
+      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 = {}
+      attributes[:key] = permitted[:key].to_s if permitted.key?(:key)
+      attributes[:scope] = permitted[:scope].to_s if permitted.key?(:scope)
+      attributes[:owner] = resolve_owner(permitted[:owner]) if permitted.key?(:owner)
+      attributes
+    end
+  end
+end

data/app/controllers/acts_as_calculator/imports_controller.rb

@@ -0,0 +1,33 @@
+# 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)
+
+      render json: SerializeImportSummary.(summary:),
+             status: summary.success? ? :ok : :unprocessable_entity
+    end
+
+    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?
+        raise ImportError, "no import document in the request body — POST JSON with at least one of " \
+                           "#{ImportDefinitions::SECTIONS.keys.join(", ")}"
+      end
+
+      body
+    end
+  end
+end

data/app/controllers/acts_as_calculator/templates_controller.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class TemplatesController < ApplicationController
+    def index
+      render json: { templates: scoped_templates.map { |template| SerializeTemplate.(template:) } }
+    end
+
+    def show
+      render json: { template: SerializeTemplate.(template:) }
+    end
+
+    def create
+      published = PublishTemplate.(**template_attributes)
+
+      render json: { template: SerializeTemplate.(template: published) }, status: :created
+    end
+
+    def destroy
+      template.destroy!
+
+      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
+
+    private
+
+    def template
+      @template ||= Template.find(params[:id])
+    end
+
+    def scoped_templates
+      templates = filter_by_key_and_scope(Template.order(:scope, :key, :version_number, :id))
+      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
+
+    def template_attributes
+      permitted = params.require(:template).permit(:key, :body, :scope, :format, owner: %i[type id])
+
+      { key: permitted[:key].to_s,
+        body: permitted[:body].to_s,
+        scope: permitted[:scope].presence,
+        format: permitted[:format].presence || Template::HTML,
+        owner: resolve_owner(permitted[:owner]) }
+    end
+  end
+end

data/app/models/acts_as_calculator/formula.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ActsAsCalculator
+  class Formula < Record
+    self.table_name = "calculator_formulas"
+
+    belongs_to :owner, polymorphic: true, optional: true
+
+    has_many :versions,
+             class_name: "ActsAsCalculator::FormulaVersion",
+             foreign_key: :formula_id,
+             inverse_of: :formula,
+             dependent: :destroy
+
+    validates :key, presence: true, uniqueness: { scope: %i[scope owner_type owner_id] }
+    validates :scope, presence: true
+
+    scope :owned_by, ->(owner) { where(owner_type: owner&.class&.polymorphic_name, owner_id: owner&.id) }
+    scope :global, -> { where(owner_type: nil, owner_id: nil) }
+  end
+end