custodian-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f7964e4623e30dd16ef4b7c9dd708f49d143ecfd98146470b7a78eb582dcebea
+  data.tar.gz: e068635b45a959416e80289cc36bb6fe2e3cb3a93fa89b81ce48a81c63c38b7a
+SHA512:
+  metadata.gz: a49ad921937a9c02817bea8da23c8761daa3c3a5af18dddb017d8853cf7fe01b7bf03b6a469e6a1c263f73043fd47af55dcda1dd509776f6a8d464bb460e4179
+  data.tar.gz: 96b332f0053a92e41c503ef9e2417228ead9dd52aeb8f1521a51c8e4c7c5c0c69b239b9eccd7002d154cf671807b14f3d53c5140778cde9e7902ce302bbad8bc

data/CHANGELOG.md

@@ -0,0 +1,67 @@
+## [Unreleased]
+
+- Require Ruby 3.2+, support Rails 7.x/8.x and ancestry 4.x/5.x explicitly.
+- Reject negative demands and non-finite, negative, or over-remaining numeric
+  action outcomes.
+- Validate resolution strictness, snapshot phases safely across threads, and
+  traverse deep trees iteratively.
+- Limit the built gem to consumer-facing code, migrations, signatures, and
+  top-level release documentation.
+
+## [0.1.0] - 2026-07-07
+
+Initial release: a domain-agnostic chain-of-custody engine over a tree of
+responsibilities, ready for satellite gems to build concrete domains on top
+of. 107 examples, 0 RuboCop offenses.
+
+### Models
+
+- `Node` — the ward: a tree (via `ancestry`) of binary or numeric demands,
+  with a polymorphic `subject` (which may be another `Node`).
+- `Graph` — a container anchored at a single root `Node`, with a
+  polymorphic, optional `owner`.
+- `Custody` — the agreement between a custodian and a ward: action name,
+  priority, JSON action params, and a validity/status model
+  (`eternal`/`fixed_term`/`punctual` × `active`/`at_risk`/`broken`/`expired`)
+  exposed via `currently_valid?`, `trustworthy?`, and `healthcheck`.
+- `CustodyNodeRule` / `CustodyRepudiatedNode` — per-descendant exceptions
+  (`exclude`/`full`/`limit_pct`/`limit_amount` rules, and outright
+  repudiations) that qualify how a `Custody` applies across its ward's
+  subtree, surfaced through `Custody#applies_to?`.
+
+### ActionRegistry
+
+- The gem's one extension point: `register`/`unregister`/`call`/
+  `registered?`/`clear!`, Symbol-normalized, Mutex-guarded.
+- Strict outcome contract: `:resolved`, `:failed`, or a non-negative
+  `Numeric`, in the same unit as the node's `demand_value`. Anything else —
+  including negative Numerics — raises immediately rather than propagating
+  a silent bug downstream.
+
+### Adjuster
+
+- `aggregate_demand` — pure, read-only consolidation of numeric demand
+  across a subtree in a single query, with binary nodes acting as a
+  magnitude firewall (they contribute no quantity to an ancestor's total,
+  but are still counted via `unresolved_binary_count`).
+- `resolve_tree` — walks a subtree post-order, consulting each node's
+  direct custodies (filtered by caller-chosen `strictness: :valid` or
+  `:trustworthy`, and by `Custody#applies_to?`), then registered phases,
+  then escalating whatever remains to the direct parent with per-level
+  encapsulation: a child's shortfall becomes part of its parent's own
+  demand, with no marker distinguishing the two at invocation time. A
+  grandparent never sees a grandchild; the full story is only
+  reconstructable from each node's `attempts` audit trail. Binary
+  escalation is supported too: a parent's custodians can be asked to act on
+  a still-pending binary descendant's behalf.
+- `register_phase` / `clear_phases!` — the hook a future sibling-generosity
+  satellite will plug into. Not built yet; only the extension point is.
+- Pure resolution throughout: neither method persists or mutates any
+  record.
+
+### Documentation
+
+- README with the project's guiding definition, vocabulary, quick start,
+  outcome contract, resolution order, and explicitly non-domain examples.
+- Eight ADRs recording the project's design decisions, from the
+  domain-agnostic-core constraint through registry defensiveness.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 lucasnshuntervoa
+
+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,204 @@
+# custodian-core
+
+The core has no business rules from any specific domain — it only knows how
+to resolve a chain of custody: identify the next responsible party, and
+demand from them the execution of the action the previous ward could not
+fulfill, climbing the tree until someone has the capacity to act.
+
+`custodian-core` is a Ruby (Rails engine) gem that implements this
+resolution mechanism over a tree of `Node` records. It ships no domain
+vocabulary — no money, no storage, no networking — only the shape of
+responsibility and the machinery to walk it. Concrete domains plug in as
+satellite gems.
+
+> ⚠️ **Early-stage (0.1.0).** The API may still change and this gem has not
+> yet been battle-tested in production. It is provided "as is", without
+> warranty of any kind (see [License](#license)). Use at your own risk.
+
+## Vocabulary
+
+- **Node** — something that needs to be resolved: the **ward**. Nodes form
+  a tree (via [ancestry](https://github.com/stefankroes/ancestry)); a node's
+  demand is either binary ("this must be done") or numeric (a quantity to
+  cover).
+- **Custody** — the agreement between a **custodian** (whoever takes on
+  responsibility for a ward) and the ward itself: which action to call, at
+  what priority, and under what validity window.
+- **custodian** — the party who took on a `Custody`. It can be anything
+  polymorphic — including another `Node`.
+- **Adjuster** — walks the tree and resolves it, invoking custodies through
+  the `ActionRegistry` and escalating what nobody could cover. Named after
+  the insurance claims adjuster: someone who reviews a policy, evaluates
+  what happened, and decides who's responsible for covering it.
+- **ActionRegistry** — the plug-in point. Host apps and satellite gems
+  register named actions here; the core never knows what an action
+  actually does.
+
+## Quick start
+
+```ruby
+root = Custodian::Core::Node.create!(demand_type: "fixed", demand_value: 100)
+child = Custodian::Core::Node.create!(demand_type: "fixed", demand_value: 50, parent: root)
+
+Custodian::Core::Custody.create!(ward: root, action_name: "cover_shortfall")
+
+Custodian::Core::ActionRegistry.register(:cover_shortfall) do |node, custody, remaining|
+  remaining # fully resolves whatever it's asked to cover
+end
+
+result = Custodian::Core::Adjuster.resolve_tree(root)
+
+result[child.id][:gap]   #=> 0.0 (BigDecimal) - resolved via escalation into root
+result[root.id][:gap]    #=> 0.0 - root's own 100 + child's inherited 50 = 150, fully covered
+result[root.id][:attempts]
+#=> [{ custody_id: 1, action_name: "cover_shortfall", outcome: 0.15e3, via: :direct }]
+```
+
+`resolve_tree` returns a Hash keyed by node id. Each entry reports what was
+`demanded`, how much of it is `own_demand` vs `inherited_shortfall`, the
+`resolved_amount` and remaining `gap`, binary-specific fields, and a full
+`attempts` audit trail (`via: :direct | :phase | :escalation`) for
+reconstructing the whole story after the fact.
+
+## The outcome contract
+
+A registered action receives `(node, custody, remaining)` and must return:
+
+- `:resolved` — fully satisfied, stop trying custodies for this node
+- `:failed` — this custodian couldn't act, try the next one
+- a non-negative `Numeric` — partial resolution, **in the same unit as the
+  node's `demand_value`** (see
+  [ADR 0004](docs/adr/0004-numeric-outcome-unit-commensurability.md); the
+  core cannot enforce unit correctness, only that the number itself is
+  well-formed)
+
+Anything else — `true`, `nil`, a `String`, a negative number — raises
+`ActionRegistry::InvalidOutcomeError` immediately. See
+[ADR 0008](docs/adr/0008-registry-defensiveness.md) for why this is
+deliberately strict rather than forgiving.
+
+## Security: action registration is a trust boundary
+
+Registered actions and phase handlers are ordinary Ruby blocks that
+`custodian-core` executes with your application's full privileges. The core
+validates only the *shape* of what an action returns — it does **not**
+sandbox what an action does. Treat registration as privileged
+configuration:
+
+- Register actions only from code you control (your app, or satellite gems
+  you trust). Never build or register an action from untrusted input.
+- Never derive an `action_name` to invoke, or an action's body, from
+  user-supplied data without validating it against a fixed allowlist of
+  known actions.
+- `action_params` on a `Custody` is passed to the action as-is; validate
+  and authorize any host-exposed path that lets an end user set
+  `action_name`, `action_params`, or custody attributes, since those
+  determine what code runs and on whose behalf.
+
+## Resolution order and encapsulation
+
+For each node, post-order (children before parents), the Adjuster tries, in
+order: **direct custodies** (by `priority_weight`, then id), then
+**registered phases** (an extension point, e.g. for a future
+sibling-generosity satellite), then **escalation**.
+
+Escalation is the gem's most distinctive idea: if a node still can't cover
+its demand after the two steps above, that shortfall is folded into its
+direct parent's own demand before the parent is even processed — with no
+marker distinguishing "my own demand" from "what my child couldn't cover."
+The parent's custodians never know a child failed; they just see a bigger
+number. This means **a grandparent never sees a grandchild** — each level
+only ever perceives one level down, exactly like a real management chain.
+The full story (who ultimately paid for whom) is only reconstructable from
+the `attempts` audit trail, not from any single node's own view. See
+[ADR 0006](docs/adr/0006-escalation-with-per-level-encapsulation.md).
+
+Binary nodes are a **magnitude firewall**: a numeric node's demand never
+aggregates through a binary ancestor, even though escalation still walks
+*into* one if it's the direct parent — aggregation and escalation are
+different mechanisms. See
+[ADR 0005](docs/adr/0005-binary-nodes-as-magnitude-firewalls.md).
+
+## Strictness: `:valid` vs `:trustworthy`
+
+`resolve_tree(root, strictness: :valid)` (the default) consults any custody
+that is currently legally valid, regardless of risk signals.
+`strictness: :trustworthy` additionally excludes custodies flagged
+`at_risk` — for callers who care not just "is this custody in force" but
+"do I actually trust it right now." See
+[ADR 0007](docs/adr/0007-strictness-as-a-caller-choice.md).
+
+## This is domain-agnostic — satellite gems bring the meaning
+
+`custodian-core` never mentions money, storage, or networking. Examples of
+what a satellite gem could layer on top, none of which live here:
+
+- **Finance**: a `custodian-payments` gem registering `:charge_card` or
+  `:draw_from_reserve` actions, where a Node's numeric demand is an amount
+  owed and escalation models who is ultimately liable for a shortfall.
+- **Storage failover**: a `custodian-storage` gem registering
+  `:replicate_to_backup`, where a binary Node represents "this object must
+  be durably stored somewhere" and custody escalates through a chain of
+  storage backends.
+- **Network routing**: a `custodian-routing` gem registering
+  `:forward_via_peer`, where demand is bandwidth to place and unresolved
+  capacity escalates to an upstream peer.
+
+## Satellites (not yet built)
+
+Planned extensions that do not exist in this gem yet:
+
+- **Sibling generosity / "brotherhood"** — a phase (via `register_phase`)
+  that lets a resolved sibling's surplus cover another sibling's shortfall
+  before escalating to the parent.
+- **Resource pools** — shared capacity a custodian can draw from across
+  multiple wards, instead of resolving each in isolation.
+- **Execution history / honor tracking** — a record of how reliably a
+  custodian has actually resolved what it took on, feeding back into future
+  eligibility decisions.
+
+## Installation
+
+### Compatibility
+
+`custodian-core` 0.1 supports Ruby 3.2 or newer, Rails 7.x and 8.x, and
+`ancestry` 4.x and 5.x. The lower Ruby bound keeps the supported runtime
+aligned with the CI matrix and with the currently supported Rails majors.
+
+This gem is not published to RubyGems yet. While it lives on GitHub only,
+add it to your host Rails application's Gemfile via git:
+
+```ruby
+gem "custodian-core", git: "https://github.com/lucasnssoftwareengineer-alt/custodian-core"
+```
+
+Once it is published to RubyGems, this becomes simply:
+
+```ruby
+gem "custodian-core"
+```
+
+Then install the engine's migrations:
+
+```sh
+bundle exec rails custodian_core:install:migrations
+bundle exec rails db:migrate
+```
+
+## Running tests
+
+```sh
+bundle exec rake       # runs both rspec and rubocop
+bundle exec rspec      # specs only
+bundle exec rubocop    # lint only
+```
+
+## Architecture decisions
+
+See [docs/adr](docs/adr/0000-index.md) for the full record of design
+decisions and their rationale.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/app/models/custodian/core/application_record.rb

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

data/app/models/custodian/core/custody.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Custodian
+  module Core
+    class Custody < ApplicationRecord
+      self.table_name = "custodian_core_custodies"
+
+      VALIDITY_TYPES = %w[eternal fixed_term punctual].freeze
+      STATUSES = %w[active at_risk broken expired].freeze
+
+      belongs_to :custodian, polymorphic: true, optional: true
+      belongs_to :ward, class_name: "Custodian::Core::Node"
+
+      has_many :node_rules, class_name: "Custodian::Core::CustodyNodeRule", dependent: :destroy
+      has_many :repudiated_nodes, class_name: "Custodian::Core::CustodyRepudiatedNode", dependent: :destroy
+
+      validates :action_name, presence: true
+      validates :priority_weight, numericality: { only_integer: true }
+      validates :validity_type, inclusion: { in: VALIDITY_TYPES }
+      validates :status, inclusion: { in: STATUSES }
+
+      # Answers only the exclusion question: is this node repudiated, or does
+      # it have an "exclude" rule? It does NOT interpret limit_pct/limit_amount
+      # rule values (i.e. it doesn't decide how much of the demand applies) -
+      # that quantitative interpretation is the Adjuster's job, in a later step.
+      def applies_to?(node)
+        return false if repudiated_nodes.exists?(node: node)
+        return false if node_rules.exists?(node: node, rule_type: "exclude")
+
+        true
+      end
+
+      def at_risk?
+        status == "at_risk"
+      end
+
+      def trustworthy?(at_time = Time.current)
+        currently_valid?(at_time) && !at_risk?
+      end
+
+      def healthcheck(at_time = Time.current)
+        return :broken if status == "broken"
+        return :expired if status == "expired"
+        return :expired unless currently_valid?(at_time)
+        return :at_risk if at_risk?
+
+        :active
+      end
+
+      def currently_valid?(at_time = Time.current)
+        return false if %w[broken expired].include?(status)
+
+        case validity_type
+        when "eternal"
+          true
+        when "fixed_term"
+          fixed_term_valid_at?(at_time)
+        when "punctual"
+          punctual_valid_at?(at_time)
+        end
+      end
+
+      private
+
+      def fixed_term_valid_at?(at_time)
+        (valid_from.nil? || at_time >= valid_from) && (valid_until.nil? || at_time <= valid_until)
+      end
+
+      def punctual_valid_at?(at_time)
+        valid_until.nil? || at_time <= valid_until
+      end
+    end
+  end
+end

data/app/models/custodian/core/custody_node_rule.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Custodian
+  module Core
+    class CustodyNodeRule < ApplicationRecord
+      self.table_name = "custodian_core_custody_node_rules"
+
+      RULE_TYPES = %w[exclude full limit_pct limit_amount].freeze
+
+      belongs_to :custody, class_name: "Custodian::Core::Custody"
+      belongs_to :node, class_name: "Custodian::Core::Node"
+
+      validates :rule_type, inclusion: { in: RULE_TYPES }
+      validates :custody_id, uniqueness: { scope: :node_id }
+      validate :rule_value_matches_rule_type
+      validate :rule_value_within_percentage_bounds
+
+      scope :for_node, ->(node) { where(node: node) }
+
+      private
+
+      def rule_value_matches_rule_type
+        if %w[exclude full].include?(rule_type)
+          errors.add(:rule_value, "must be blank when rule_type is #{rule_type}") if rule_value.present?
+        elsif rule_value.nil?
+          errors.add(:rule_value, "can't be blank when rule_type is #{rule_type}")
+        end
+      end
+
+      def rule_value_within_percentage_bounds
+        return unless rule_type == "limit_pct" && rule_value.present?
+
+        return if rule_value.positive? && rule_value <= 100
+
+        errors.add(:rule_value, "must be greater than 0 and less than or equal to 100 for limit_pct")
+      end
+    end
+  end
+end

data/app/models/custodian/core/custody_repudiated_node.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Custodian
+  module Core
+    class CustodyRepudiatedNode < ApplicationRecord
+      self.table_name = "custodian_core_custody_repudiated_nodes"
+
+      belongs_to :custody, class_name: "Custodian::Core::Custody"
+      belongs_to :node, class_name: "Custodian::Core::Node"
+
+      validates :custody_id, uniqueness: { scope: :node_id }
+    end
+  end
+end

data/app/models/custodian/core/graph.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Custodian
+  module Core
+    class Graph < ApplicationRecord
+      self.table_name = "custodian_core_graphs"
+
+      belongs_to :owner, polymorphic: true, optional: true
+      belongs_to :root_node, class_name: "Custodian::Core::Node"
+
+      validate :root_node_must_be_a_root
+
+      private
+
+      def root_node_must_be_a_root
+        return if root_node.nil? || root_node.root?
+
+        errors.add(:root_node, "must be a root node (cannot have a parent)")
+      end
+    end
+  end
+end

data/app/models/custodian/core/node.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "ancestry"
+
+module Custodian
+  module Core
+    class Node < ApplicationRecord
+      self.table_name = "custodian_core_nodes"
+
+      has_ancestry
+
+      belongs_to :subject, polymorphic: true, optional: true
+
+      DEMAND_TYPES = %w[binary fixed variable_manual variable_by_tag].freeze
+
+      validates :demand_type, presence: true, inclusion: { in: DEMAND_TYPES }
+      validates :demand_value, numericality: { greater_than_or_equal_to: 0 }, allow_nil: true
+      validate :demand_value_matches_demand_type
+
+      # Node deliberately has no graph_id column: graph membership is resolved
+      # via the ancestry root instead, to avoid an unused foreign key.
+      def graph
+        Graph.find_by(root_node: root)
+      end
+
+      private
+
+      def demand_value_matches_demand_type
+        if demand_type == "binary"
+          errors.add(:demand_value, "must be blank when demand_type is binary") if demand_value.present?
+        elsif demand_value.nil?
+          errors.add(:demand_value, "can't be blank unless demand_type is binary")
+        end
+      end
+    end
+  end
+end

data/custodian-core.gemspec

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "lib/custodian/core/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "custodian-core"
+  spec.version = Custodian::Core::VERSION
+  spec.authors = ["Lucas nunes de sousa"]
+  spec.email = ["lucas.ns.software.engineer@gmail.com"]
+  spec.homepage = "https://github.com/lucasnssoftwareengineer-alt/custodian-core"
+  spec.metadata["source_code_uri"] = "https://github.com/lucasnssoftwareengineer-alt/custodian-core"
+  spec.metadata["changelog_uri"] = "https://github.com/lucasnssoftwareengineer-alt/custodian-core/blob/main/CHANGELOG.md"
+  spec.summary = "A domain-agnostic chain-of-custody engine for Ruby."
+  spec.description = "Custodian::Core resolves a chain of custody over a tree of responsibilities: " \
+                     "it identifies the next responsible party and demands the action a previous " \
+                     "ward could not fulfill, climbing the tree until someone can act. It carries " \
+                     "no business rules from any specific domain - concrete domains are implemented " \
+                     "as satellite gems that register actions into this core via a registry."
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Keep the package independent from Git and deliberately limited to files
+  # useful to consumers. Development configuration, specs, CI, and internal
+  # architecture records remain in the repository but not in the gem.
+  spec.files = Dir.chdir(__dir__) do
+    %w[CHANGELOG.md LICENSE.txt README.md custodian-core.gemspec] +
+      Dir.glob(%w[app/**/*.rb db/**/*.rb lib/**/*.rb sig/**/*.rbs])
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # This gem is a Rails engine so that satellite gems can rely on it to ship
+  # ActiveRecord models and migrations in later steps. We depend on the
+  # specific Rails components isolate_namespace/ActiveRecord actually need
+  # (actionpack for Rails::Engine's route set, activerecord for models)
+  # rather than the "rails" umbrella gem, to avoid pulling in ActionMailer,
+  # ActionCable, ActionText, ActiveStorage, ActionView, Nokogiri, etc. into a
+  # domain-agnostic core (see docs/adr/0001-domain-agnostic-core.md).
+  spec.add_dependency "actionpack", ">= 7.0", "< 9.0"
+  spec.add_dependency "activerecord", ">= 7.0", "< 9.0"
+  spec.add_dependency "activesupport", ">= 7.0", "< 9.0"
+  spec.add_dependency "ancestry", ">= 4.0", "< 6.0"
+  spec.add_dependency "railties", ">= 7.0", "< 9.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/db/migrate/20260703015208_create_custodian_core_nodes.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+class CreateCustodianCoreNodes < ActiveRecord::Migration[7.0]
+  def change
+    create_table :custodian_core_nodes do |t|
+      t.string :ancestry, index: true
+
+      t.string :subject_type
+      t.bigint :subject_id
+
+      t.string :demand_type, null: false
+      t.decimal :demand_value, precision: 15, scale: 4
+
+      t.timestamps
+    end
+
+    add_index :custodian_core_nodes, %i[subject_type subject_id]
+  end
+end

data/db/migrate/20260703103004_create_custodian_core_graphs.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class CreateCustodianCoreGraphs < ActiveRecord::Migration[7.0]
+  def change
+    create_table :custodian_core_graphs do |t|
+      t.string :owner_type
+      t.bigint :owner_id
+
+      t.bigint :root_node_id, null: false
+
+      t.timestamps
+    end
+
+    add_index :custodian_core_graphs, %i[owner_type owner_id]
+    add_foreign_key :custodian_core_graphs, :custodian_core_nodes, column: :root_node_id
+  end
+end

data/db/migrate/20260703215106_create_custodian_core_custodies.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class CreateCustodianCoreCustodies < ActiveRecord::Migration[7.0]
+  def change
+    create_table :custodian_core_custodies do |t|
+      t.string :custodian_type
+      t.bigint :custodian_id
+
+      t.bigint :ward_id, null: false
+
+      t.string :action_name, null: false
+      t.json :action_params, null: false, default: {}
+
+      t.integer :priority_weight, null: false, default: 0
+
+      t.string :validity_type, null: false, default: "eternal"
+      t.datetime :valid_from
+      t.datetime :valid_until
+
+      t.string :status, null: false, default: "active"
+
+      t.timestamps
+    end
+
+    add_index :custodian_core_custodies, %i[custodian_type custodian_id],
+              name: "index_custodian_core_custodies_on_custodian"
+    add_foreign_key :custodian_core_custodies, :custodian_core_nodes, column: :ward_id
+  end
+end

data/db/migrate/20260707000238_create_custodian_core_custody_node_rules.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateCustodianCoreCustodyNodeRules < ActiveRecord::Migration[7.0]
+  def change
+    create_table :custodian_core_custody_node_rules do |t|
+      t.bigint :custody_id, null: false
+      t.bigint :node_id, null: false
+
+      t.string :rule_type, null: false
+      t.decimal :rule_value, precision: 15, scale: 4
+
+      t.timestamps
+    end
+
+    add_index :custodian_core_custody_node_rules, %i[custody_id node_id],
+              unique: true, name: "index_custody_node_rules_on_custody_and_node"
+    add_foreign_key :custodian_core_custody_node_rules, :custodian_core_custodies, column: :custody_id
+    add_foreign_key :custodian_core_custody_node_rules, :custodian_core_nodes, column: :node_id
+  end
+end

data/db/migrate/20260707000247_create_custodian_core_custody_repudiated_nodes.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class CreateCustodianCoreCustodyRepudiatedNodes < ActiveRecord::Migration[7.0]
+  def change
+    create_table :custodian_core_custody_repudiated_nodes do |t|
+      t.bigint :custody_id, null: false
+      t.bigint :node_id, null: false
+
+      t.timestamps
+    end
+
+    add_index :custodian_core_custody_repudiated_nodes, %i[custody_id node_id],
+              unique: true, name: "index_custody_repudiated_nodes_on_custody_and_node"
+    add_foreign_key :custodian_core_custody_repudiated_nodes, :custodian_core_custodies, column: :custody_id
+    add_foreign_key :custodian_core_custody_repudiated_nodes, :custodian_core_nodes, column: :node_id
+  end
+end