activecypher 0.5.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d529adab6eb5478a435e3061d317f742373617d8460b14f545d2b66b03cd37d
-  data.tar.gz: 35726eeafd44cc915e3731b3c4557e63f6ace655b87c28761e1ebc426d989af1
+  metadata.gz: 3901e0713d002b9c8061ffe4f3e7e8b85cceb4faf3216df23c91cab136654356
+  data.tar.gz: ba8088d2981a28e99eca7e171553f94696c0ed940a51c4ba53fa03210dce3be8
 SHA512:
-  metadata.gz: 0cdb35c5ebeb4d5774a2ff203b6322ef26e1f1abcdaac97b93cea64125322454fdd95b6a91117ced49ea5391815b96e84f274f96fd57725f0de65b1916aef7cf
-  data.tar.gz: 258b065dc249ac957e7eed9025663dbbb12e7f0927dd7555793365bbbbbad36ffff4458aba48f99baedfecc02c214a490ba5e2cf68a9244d27a284291951f79f
+  metadata.gz: 1e0923e31a2d8a3bfea68047870de373ab012ecc90d6164bacd43f8c7a3af1f88ce4c9051b4e4d53ca541d738cefeb988da3e508995557d2c51277870a39da60
+  data.tar.gz: 63126e6704aa13ce3094d6aafc5590eb3d9786a58d065590fb68d98b5234ed5f7d125147663928cc7baadab3da623b5aafc9432b8324a4957e11b131632e8bf8

data/lib/active_cypher/base.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+require 'active_model'
+require 'active_model/validations'
+require 'active_model/callbacks'
+require 'active_model/attributes'
+require 'active_model/dirty'
+
 module ActiveCypher
   # @!parse
   #   # The One True Base Class. All node models must kneel before it.
@@ -8,18 +14,25 @@ module ActiveCypher
     # @!attribute [rw] connects_to_mappings
     #   @return [Hash] Because every base class needs a mapping it will never use directly.
     class_attribute :connects_to_mappings, default: {}
+
+    # Rails/ActiveModel foundations
     include Logging
+    include ActiveModel::Model
+    include ActiveModel::Validations
+    include ActiveModel::Callbacks
+    include ActiveModel::Attributes
+    include ActiveModel::Dirty
 
     # Let's just include every concern we can find, because why not.
-    include Model::Querying # Must be before Core so Core can override its methods
     include Model::Core
+    include Model::Callbacks
+    include Model::Labelling
+    include Model::Querying
+    include Model::Abstract
     include Model::Attributes
     include Model::ConnectionOwner
-    include Model::Callbacks
     include Model::Persistence
-    include Model::ConnectionHandling
     include Model::Destruction
-    include Model::Abstract
     include Model::Countable
     include Model::Inspectable
 
@@ -29,15 +42,22 @@ module ActiveCypher
       # If you still don't have a connection, you get an error. It's the circle of life.
       # @return [Object] The connection instance
       def connection
-        if (pool = connection_handler.pool(current_role, current_shard))
-          return pool.connection
+        # Determine the current role (e.g., :writing, :reading)
+        # ActiveCypher::RuntimeRegistry.current_role defaults to :writing
+        # Only use db_key for pool lookup
+        if respond_to?(:connects_to_mappings) && connects_to_mappings.is_a?(Hash)
+          db_key = connects_to_mappings[:writing] # or whichever role is appropriate
+          if db_key && (pool = connection_handler.pool(db_key))
+            return pool.connection
+          end
         end
 
-        # fall back to a per‑model connection created by establish_connection
         return @connection if defined?(@connection) && @connection&.active?
 
         raise ActiveCypher::ConnectionNotEstablished,
-              "No pool for role=#{current_role.inspect} shard=#{current_shard.inspect}"
+              "No connection pool found for graph #{name}, db_key=#{db_key.inspect}. " \
+              'Ensure `connects_to` is configured for this model or its ancestors, ' \
+              'and `cypher_databases.yml` has the corresponding entries.'
       end
     end
 

data/lib/active_cypher/bolt/driver.rb

@@ -12,31 +12,21 @@ module ActiveCypher
     class Driver
       DEFAULT_POOL_SIZE = ENV.fetch('BOLT_POOL_SIZE', 10).to_i
 
-      # Map URI schemes ➞ security/verification flags
-      # Because nothing says "enterprise" like six ways to spell 'bolt'.
-      SCHEMES = {
-        'bolt' => { secure: false, verify: true },
-        'bolt+s' => { secure: true, verify: true },
-        'bolt+ssc' => { secure: true, verify: false },
-        'neo4j' => { secure: false, verify: true },
-        'neo4j+s' => { secure: true, verify: true },
-        'neo4j+ssc' => { secure: true, verify: false }
-      }.freeze
-
       # Initializes the driver, because you can't spell "abstraction" without "action".
       #
       # @param uri [String] The Bolt URI
       # @param adapter [Object] The adapter instance
       # @param auth_token [Hash] Authentication token
       # @param pool_size [Integer] Connection pool size
-      def initialize(uri:, adapter:, auth_token:, pool_size: DEFAULT_POOL_SIZE)
-        @uri     = URI(uri)
-        scheme   = SCHEMES.fetch(@uri.scheme) { raise ArgumentError, "Unsupported Bolt scheme: #{@uri.scheme}" }
+      # @param secure [Boolean] Use SSL (default: false)
+      # @param verify_cert [Boolean] Verify SSL certificate (default: true)
+      def initialize(uri:, adapter:, auth_token:, pool_size: DEFAULT_POOL_SIZE, secure: false, verify_cert: true)
+        @uri = URI(uri)
 
         @adapter       = adapter
         @auth          = auth_token
-        @secure        = scheme[:secure]
-        @verify_cert   = scheme[:verify]
+        @secure        = secure
+        @verify_cert   = verify_cert
 
         # Create a connection pool with the specified size
         # Because one connection is never enough for true disappointment.

data/lib/active_cypher/bolt/transaction.rb

@@ -5,7 +5,7 @@ module ActiveCypher
     # Manages transaction state (BEGIN/COMMIT/ROLLBACK) and runs queries within a transaction.
     class Transaction
       include Instrumentation
-      attr_reader :bookmarks, :metadata
+      attr_reader :bookmarks, :metadata, :connection
 
       # Initializes a new Transaction instance.
       #
@@ -35,10 +35,10 @@ module ActiveCypher
           # Send RUN message
           run_metadata = {}
           run_msg = Messaging::Run.new(query_str, parameters, run_metadata)
-          @connection.write_message(run_msg)
+          connection.write_message(run_msg)
 
           # Read response to RUN
-          response = @connection.read_message
+          response = connection.read_message
           qid = -1
           fields = []
 
@@ -53,7 +53,7 @@ module ActiveCypher
             pull_metadata = { 'n' => -1 }
             pull_metadata['qid'] = qid if qid != -1
             pull_msg = Messaging::Pull.new(pull_metadata)
-            @connection.write_message(pull_msg)
+            connection.write_message(pull_msg)
 
             # Process PULL response(s)
             records = []
@@ -61,7 +61,7 @@ module ActiveCypher
 
             # Read messages until we get a SUCCESS (or FAILURE)
             loop do
-              msg = @connection.read_message
+              msg = connection.read_message
               case msg
               when Messaging::Record
                 # Store record with raw values - processing will happen in the adapter
@@ -108,10 +108,10 @@ module ActiveCypher
         instrument_transaction(:commit, object_id) do
           # Send COMMIT message
           commit_msg = Messaging::Commit.new
-          @connection.write_message(commit_msg)
+          connection.write_message(commit_msg)
 
           # Read response to COMMIT
-          response = @connection.read_message
+          response = connection.read_message
 
           case response
           when Messaging::Success
@@ -163,10 +163,10 @@ module ActiveCypher
         instrument_transaction(:rollback, object_id) do
           # Send ROLLBACK message
           rollback_msg = Messaging::Rollback.new
-          @connection.write_message(rollback_msg)
+          connection.write_message(rollback_msg)
 
           # Read response to ROLLBACK
-          response = @connection.read_message
+          response = connection.read_message
 
           case response
           when Messaging::Success

data/lib/active_cypher/connection_adapters/abstract_adapter.rb

@@ -49,6 +49,34 @@ module ActiveCypher
         end
       end
 
+      # Get current adapter type for ID handling
+      # Helper for generating ID-related Cypher functions that are database-specific
+      module CypherFunction
+        # Generate ID equality clause with the ID value embedded in the query for Memgraph
+        def self.id_equals(var, id_value, adapter)
+          func = id_function(adapter)
+          "#{func}(#{var}) = #{id_value}"
+        end
+
+        # Generate ID equality clause using a parameterized ID value for Neo4j
+        def self.id_equals_param(var, param_name, adapter)
+          func = id_function(adapter)
+          "#{func}(#{var}) = $#{param_name}"
+        end
+
+        # Generate a node variable with ID predicate
+        def self.node_with_id(node_var, id_value, adapter)
+          func = id_function(adapter)
+          "#{func}(#{node_var}) = #{id_value}"
+        end
+
+        # Return ID expression
+        def self.return_id(var, as_name, adapter)
+          func = id_function(adapter)
+          "#{func}(#{var}) AS #{as_name}"
+        end
+      end
+
       # Turns rows into symbols, because Rubyists fear strings.
       # @param rows [Array<Hash>] The rows to process
       # @return [Array<Hash>] The processed rows

data/lib/active_cypher/connection_adapters/abstract_bolt_adapter.rb

@@ -63,7 +63,7 @@ module ActiveCypher
 
         instrument_query(cypher, params, context: context, metadata: { db: db, access_mode: access_mode }) do
           session = Bolt::Session.new(connection, database: db)
-          result  = session.run(cypher, prepare_params(params), access_mode:)
+          result  = session.run(cypher, prepare_params(params), mode: access_mode)
           rows    = result.respond_to?(:to_a) ? result.to_a : result
           session.close
           rows

data/lib/active_cypher/connection_adapters/memgraph_adapter.rb

@@ -3,6 +3,38 @@
 module ActiveCypher
   module ConnectionAdapters
     class MemgraphAdapter < AbstractBoltAdapter
+      # Register this adapter with the registry
+      Registry.register('memgraph', self)
+
+      # Use id() for Memgraph instead of elementId()
+      ID_FUNCTION = 'id'
+
+      # Helper methods for Cypher query generation with IDs
+      def self.with_direct_id(id)
+        "id(r) = #{id}"
+      end
+
+      def self.with_param_id
+        'id(r) = $id'
+      end
+
+      def self.with_direct_node_ids(a_id, b_id)
+        "id(p) = #{a_id} AND id(h) = #{b_id}"
+      end
+
+      def self.with_param_node_ids
+        'id(p) = $from_id AND id(h) = $to_id'
+      end
+
+      def self.return_id
+        'id(r) AS rid'
+      end
+
+      # Return self as id_handler for compatibility with tests
+      def id_handler
+        self.class
+      end
+
       # Memgraph defaults to **implicit auto‑commit** transactions :contentReference[oaicite:1]{index=1},
       # so we simply run the Cypher and return the rows.
       def execute_cypher(cypher, params = {}, ctx = 'Query')
@@ -34,6 +66,18 @@ module ActiveCypher
         true
       end
 
+      # Override prepare_params to handle arrays correctly for Memgraph
+      # Memgraph's UNWIND requires actual arrays/lists, not maps
+      def prepare_params(raw)
+        case raw
+        when Hash  then raw.transform_keys(&:to_s).transform_values { |v| prepare_params(v) }
+        when Array then raw.map { |v| prepare_params(v) } # Keep arrays as arrays for Memgraph
+        when Time, Date, DateTime then raw.iso8601
+        when Symbol then raw.to_s
+        else raw # String/Integer/Float/Boolean/NilClass
+        end
+      end
+
       class ProtocolHandler < AbstractProtocolHandler
         def extract_version(agent)
           agent[%r{Memgraph/([\d.]+)}, 1] || 'unknown'

data/lib/active_cypher/connection_adapters/neo4j_adapter.rb

@@ -3,6 +3,32 @@
 module ActiveCypher
   module ConnectionAdapters
     class Neo4jAdapter < AbstractBoltAdapter
+      Registry.register('neo4j', self)
+
+      # Use elementId() for Neo4j
+      ID_FUNCTION = 'elementId'
+
+      # Helper methods for Cypher query generation with IDs
+      def self.with_direct_id(id)
+        "elementId(r) = #{id}"
+      end
+
+      def self.with_param_id
+        'elementId(r) = $id'
+      end
+
+      def self.with_direct_node_ids(a_id, b_id)
+        "elementId(p) = #{a_id} AND elementId(h) = #{b_id}"
+      end
+
+      def self.with_param_node_ids
+        'elementId(p) = $from_id AND elementId(h) = $to_id'
+      end
+
+      def self.return_id
+        'elementId(r) AS rid'
+      end
+
       def execute_cypher(cypher, params = {}, ctx = 'Query')
         connect
         session = connection.session # thin wrapper around Bolt::Session

data/lib/active_cypher/connection_adapters/registry.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module ConnectionAdapters
+    # Registry: Because every adapter wants to feel special, and every ORM needs a secret society.
+    # This class is the adapter speakeasy—register your adapter, get on the list, and maybe, just maybe,
+    # you'll get to connect to a database tonight. Under the hood, it's just a hash, a dash of Ruby mischief,
+    # and the occasional existential dread when you realize your adapter isn't registered.
+    class Registry
+      class << self
+        # The sacred scroll of adapters. Not inherited, not shared—just ours.
+        def adapters
+          @adapters ||= {}
+        end
+
+        # Register an adapter class for a specific database type.
+        # Because every adapter wants to be chosen, but only a few make the cut.
+        # @param adapter_type [String] The adapter type name (e.g., 'neo4j', 'memgraph')
+        # @param adapter_class [Class] The adapter class to register
+        def register(adapter_type, adapter_class)
+          adapters[adapter_type.to_s.downcase] = adapter_class
+        end
+
+        # Get all registered adapters (for those who like to peek behind the curtain).
+        # @return [Hash] The hash of registered adapters
+        def adapters_dup
+          adapters.dup
+        end
+
+        # Summon an adapter from a connection URL.
+        # @param url [String] Connection URL (e.g., "neo4j://user:pass@localhost:7687")
+        # @param options [Hash] Additional options for the connection
+        # @return [AbstractAdapter] An instance of the appropriate adapter
+        def create_from_url(url, options = {})
+          resolver = ActiveCypher::ConnectionUrlResolver.new(url)
+          config = resolver.to_hash
+          return nil unless config
+
+          create_from_config(config, options)
+        end
+
+        # Conjure an adapter from a configuration hash.
+        # @param config [Hash] Configuration hash with adapter, host, port, etc.
+        # @param options [Hash] Additional options for the connection
+        # @return [AbstractAdapter] An instance of the appropriate adapter, or a cryptic error if you angered the registry spirits.
+        def create_from_config(config, options = {})
+          adapter_type = config[:adapter].to_s.downcase
+          adapter_class = adapters[adapter_type]
+          unless adapter_class
+            # Try to require the adapter file dynamically
+            begin
+              require "active_cypher/connection_adapters/#{adapter_type}_adapter"
+            rescue LoadError
+              # Ignore, will raise below
+            end
+            adapter_class = adapters[adapter_type]
+          end
+          raise ActiveCypher::ConnectionError, "No adapter registered for '#{adapter_type}'. The registry is silent (and so is require)." unless adapter_class
+
+          full_config = config.merge(options)
+          adapter_class.new(full_config)
+        end
+
+        # Creates a Bolt driver from a connection URL, because sometimes you want to skip the foreplay and go straight to disappointment.
+        # @param url [String] Connection URL
+        # @param pool_size [Integer] Connection pool size
+        # @param options [Hash] Additional options
+        # @return [Bolt::Driver] The configured driver, or a ticket to the debugging underworld.
+        def create_driver_from_url(url, pool_size: 5, options: {})
+          resolver = ActiveCypher::ConnectionUrlResolver.new(url)
+          config = resolver.to_hash
+          return nil unless config
+
+          adapter = create_from_config(config, options)
+          return nil unless adapter
+
+          # Always use 'bolt' scheme for driver creation, regardless of adapter
+          uri = "bolt://#{config[:host]}:#{config[:port]}"
+          auth_token = {
+            scheme: 'basic',
+            principal: config[:username],
+            credentials: config[:password]
+          }
+          ActiveCypher::Bolt::Driver.new(
+            uri: uri,
+            adapter: adapter,
+            auth_token: auth_token,
+            pool_size: pool_size,
+            secure: config[:ssl] ? true : false,
+            verify_cert: config[:ssc] ? false : true
+          )
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/connection_handler.rb

@@ -2,8 +2,23 @@
 
 module ActiveCypher
   class ConnectionHandler
-    def initialize = @role_shard_map = Hash.new { |h, k| h[k] = {} }
-    def set(role, shard, pool) = (@role_shard_map[role][shard] = pool)
-    def pool(role, shard)      = @role_shard_map.dig(role, shard)
+    def initialize
+      # One-level hash: db_key -> pool
+      @db_key_map = {}
+    end
+
+    # Set a connection pool
+    # @param db_key [Symbol] The database key (e.g., :primary, :neo4j)
+    # @param pool [ConnectionPool] The connection pool
+    def set(db_key, pool)
+      @db_key_map[db_key.to_sym] = pool
+    end
+
+    # Get a connection pool
+    # @param db_key [Symbol] The database key (e.g., :primary, :neo4j)
+    # @return [ConnectionPool, nil] The connection pool, or nil if not found
+    def pool(db_key)
+      @db_key_map[db_key.to_sym]
+    end
   end
 end

data/lib/active_cypher/connection_pool.rb

@@ -5,7 +5,7 @@ require 'timeout'
 
 module ActiveCypher
   class ConnectionPool
-    attr_reader :spec
+    attr_reader :spec, :connection_key
 
     def initialize(spec)
       @spec = spec.symbolize_keys
@@ -44,28 +44,10 @@ module ActiveCypher
         conn = @conn_ref.value
         return conn if conn&.active?
 
-        # Slow path —create a new connection with retry logic
-        retries = 0
-        max_retries = @spec[:max_retries]
-
-        begin
-          new_conn = build_connection
-          @conn_ref.set(new_conn)
-          @retry_count.set(0) # Reset retry count on success
-          return new_conn
-        rescue StandardError => e
-          retries += 1
-          if retries <= max_retries
-            # Exponential backoff
-            sleep_time = 0.1 * (2**(retries - 1))
-            sleep(sleep_time)
-            retry
-          else
-            # Track persistent failures
-            @retry_count.update { |count| count + 1 }
-            raise ConnectionError, "Failed to establish connection after #{max_retries} attempts: #{e.message}"
-          end
-        end
+        # Create a new connection
+        new_conn = build_connection
+        @conn_ref.set(new_conn)
+        return new_conn
       end
     end
     alias checkout connection

data/lib/active_cypher/connection_url_resolver.rb

@@ -15,6 +15,12 @@ module ActiveCypher
   # - memgraph+ssl://
   # - memgraph+ssc://
   #
+  # Database resolution:
+  # - If specified in path: neo4j://localhost:7687/custom_db → db=custom_db
+  # - Otherwise defaults based on adapter:
+  #   - neo4j://localhost:7687 → db=neo4j
+  #   - memgraph://localhost:7687 → db=memgraph
+  #
   # The output of to_hash follows a consistent pattern:
   # {
   #   adapter: "neo4j", # or "memgraph"
@@ -22,7 +28,7 @@ module ActiveCypher
   #   password: "pass",
   #   host: "localhost",
   #   port: 7687,
-  #   database: nil, # or optional
+  #   database: "neo4j", # or "memgraph" or custom path value
   #   ssl: true,
   #   ssc: false,
   #   options: {} # future-proof for params like '?timeout=30'
@@ -83,8 +89,13 @@ module ActiveCypher
       options = extract_query_params(uri.query)
 
       # Extract database from path, if present
-      database = uri.path.empty? ? nil : uri.path.sub(%r{^/}, '')
-      database = nil if database&.empty?
+      path_database = uri.path.empty? ? nil : uri.path.sub(%r{^/}, '')
+      path_database = nil if path_database&.empty?
+
+      # Determine database using factory pattern:
+      # 1. Use path database if specified
+      # 2. Otherwise fall back to adapter name as default
+      database = path_database || adapter
 
       # The to_s conversion handles nil values
       username = uri.user.to_s.empty? ? nil : CGI.unescape(uri.user)

data/lib/active_cypher/fixtures/dsl_context.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Context for evaluating fixture profile DSL files.
+    # Provides node and relationship methods for use in profiles.
+    class DSLContext
+      attr_reader :nodes, :relationships
+
+      def initialize
+        @nodes = []
+        @relationships = []
+        @refs = {}
+      end
+
+      # DSL: node :ref, ModelClass, props
+      def node(ref, model_class, **props)
+        raise ArgumentError, "Duplicate node ref: #{ref.inspect}" if @refs.key?(ref)
+
+        @refs[ref] = :node
+        @nodes << { ref: ref, model_class: model_class, props: props }
+      end
+
+      # DSL: relationship :ref, :from_ref, :TYPE, :to_ref, props
+      def relationship(ref, from_ref, type, to_ref, **props)
+        raise ArgumentError, "Duplicate relationship ref: #{ref.inspect}" if @refs.key?(ref)
+        raise ArgumentError, "Unknown from_ref: #{from_ref.inspect}" unless @refs.key?(from_ref)
+        raise ArgumentError, "Unknown to_ref: #{to_ref.inspect}" unless @refs.key?(to_ref)
+
+        @refs[ref] = :relationship
+        @relationships << {
+          ref: ref,
+          from_ref: from_ref,
+          type: type,
+          to_ref: to_ref,
+          props: props
+        }
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/evaluator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    # Evaluator orchestrates node and relationship creation for a fixture profile.
+    class Evaluator
+      def initialize(registry: Registry, node_builder: NodeBuilder.new, rel_builder: RelBuilder.new)
+        @registry = registry
+        @node_builder = node_builder
+        @rel_builder = rel_builder
+      end
+
+      # Evaluate a sequence of DSL instructions (AST or direct calls).
+      # Each instruction is a hash: { type: :node/:relationship, args: [...] }
+      def evaluate(instructions)
+        instructions.each do |inst|
+          case inst[:type]
+          when :node
+            ref = inst[:ref]
+            model_class = inst[:model_class]
+            props = inst[:props]
+            @node_builder.build(ref, model_class, props)
+          when :relationship
+            ref = inst[:ref]
+            from_ref = inst[:from_ref]
+            type = inst[:rel_type]
+            to_ref = inst[:to_ref]
+            props = inst[:props]
+            @rel_builder.build(ref, from_ref, type, to_ref, props)
+          else
+            raise ArgumentError, "Unknown instruction type: #{inst[:type]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/fixtures/node_builder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Fixtures
+    class NodeBuilder
+      # Builds a node and registers it like a bouncer at a VIP graph party.
+      #
+      # @param ref [Symbol, String] Logical ref name (e.g., :john, :spaceship_42)
+      # @param model_class [Class] The model class (must know how to connect and label itself)
+      # @param props [Hash] Properties to assign to the node
+      # @return [Object] Instantiated model object with DB-assigned internal_id
+      def self.build(ref, model_class, props)
+        conn = model_class.connection
+        labels = model_class.labels
+
+        # Because even Cypher likes a well-dressed node.
+        label_clause = labels.map { |label| "`#{label}`" }.join(':')
+
+        # Build and fire the CREATE query.
+        # We use id(n) because elementId(n) lies to us with strings.
+        cypher = <<~CYPHER
+          CREATE (n:#{label_clause} $props)
+          RETURN n, id(n) AS internal_id, properties(n) AS props
+        CYPHER
+
+        result = conn.execute_cypher(cypher, props: props)
+        record = result.first
+
+        # Extract properties returned by the DB
+        node_props = record[:props] || record['props'] || {}
+        node_props['internal_id'] = record[:internal_id] || record['internal_id']
+
+        # Instantiate and tag it like we own it
+        instance = model_class.instantiate(node_props)
+        Registry.add(ref, instance)
+        instance
+      end
+
+      # Bulk create nodes. Still uses single `CREATE` per node,
+      # just slices the list to avoid melting your graph engine.
+      #
+      # @param nodes [Array<Hash>] List of { ref:, model_class:, props: }
+      # @param batch_size [Integer] How many to process per slice
+      def self.bulk_build(nodes, batch_size: 200)
+        nodes.each_slice(batch_size) do |batch|
+          batch.each do |node|
+            build(node[:ref], node[:model_class], node[:props])
+          end
+        end
+      end
+    end
+  end
+end