autonoma-ai 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eadf302b401291f69a0046c7fa35232a31266b25babdcf681fa526eb55a031c7
+  data.tar.gz: b67501339a7e2b550e11c68edbd12a244565e6dde13f93f5661dfd37325b0ab4
+SHA512:
+  metadata.gz: 824aa95f01aa67791daac6eb17ae4750527b58f80793244c0c16237946415f35cd34cd8a0c25a16b3be9225ae101463b45baaa7cec5383bd407e5914d7eb1581
+  data.tar.gz: 5b051dac04a96a1949d02fd1e6ea2a74883f3a6d4874df25f57cc0a381d9fc91ec711a07e0439facb288bf0c28deab376e593b7346e01fb800420900657633ad

data/lib/autonoma/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Autonoma
+  class AutonomaError < StandardError
+    attr_reader :message, :code, :status
+
+    def initialize(message, code, status)
+      @message = message
+      @code = code
+      @status = status
+      super(message)
+    end
+  end
+
+  module Errors
+    def self.invalid_signature
+      AutonomaError.new("Invalid signature", "INVALID_SIGNATURE", 401)
+    end
+
+    def self.invalid_body(detail)
+      AutonomaError.new("Invalid body: #{detail}", "INVALID_BODY", 400)
+    end
+
+    def self.unknown_action(action)
+      AutonomaError.new("Unknown action: #{action}", "UNKNOWN_ACTION", 400)
+    end
+
+    def self.production_blocked
+      AutonomaError.new("Blocked in production", "PRODUCTION_BLOCKED", 404)
+    end
+
+    def self.invalid_refs_token(detail)
+      AutonomaError.new("Invalid refs token: #{detail}", "INVALID_REFS_TOKEN", 403)
+    end
+
+    def self.same_secrets
+      AutonomaError.new(
+        "sharedSecret and signingSecret must be different. The shared secret is known by Autonoma; the signing secret must be private.",
+        "SAME_SECRETS",
+        500
+      )
+    end
+  end
+end

data/lib/autonoma/factory.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "types"
+
+module Autonoma
+  module Factory
+    # Define a factory for creating entities.
+    #
+    # input_fields is required: an array of hashes {name:, type:, required:}
+    # where type is one of 'string', 'integer', 'number', 'boolean',
+    # 'timestamp', 'date', 'uuid', 'json'.
+    #
+    # The factory's create callable receives a validated Hash and a
+    # FactoryContext, and must return a Hash with at least an "id" key.
+    #
+    # teardown is optional; without it the SDK has no way to remove rows
+    # the factory created.
+    def self.define_factory(create:, input_fields:, teardown: nil)
+      raise ArgumentError, 'Factory definition must include a callable "create"' unless create.respond_to?(:call)
+
+      if teardown && !teardown.respond_to?(:call)
+        raise ArgumentError, 'Factory "teardown" must be callable if provided'
+      end
+
+      if input_fields.nil? || !input_fields.is_a?(Array) || input_fields.empty?
+        raise ArgumentError,
+              "Factory must declare `input_fields: [...]`. The SDK derives the discover " \
+              "schema from it; there is no automatic fallback."
+      end
+
+      FactoryDefinition.new(create: create, teardown: teardown, input_fields: input_fields)
+    end
+  end
+end

data/lib/autonoma/fingerprint.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module Autonoma
+  module Fingerprint
+    # Compute a 16-char hex fingerprint of any JSON-serializable value.
+    def self.fingerprint(value)
+      normalized = sort_keys(value)
+      json_str = JSON.generate(normalized)
+      OpenSSL::Digest::SHA256.hexdigest(json_str)[0, 16]
+    end
+
+    def self.sort_keys(obj)
+      case obj
+      when Hash
+        obj.sort.to_h.transform_values { |v| sort_keys(v) }
+      when Array
+        obj.map { |v| sort_keys(v) }
+      else
+        obj
+      end
+    end
+
+    private_class_method :sort_keys
+  end
+end

data/lib/autonoma/graph.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Autonoma
+  module Graph
+    # Topological sort of nodes by FK dependency edges.
+    # Returns {"sorted" => [...], "cycles" => [[...]]}.
+    def self.topo_sort(nodes, edges)
+      node_set = nodes.to_set
+
+      # Filter to only edges between known nodes, skip self-referential
+      relevant_edges = edges.select do |e|
+        e["from"] != e["to"] && node_set.include?(e["from"]) && node_set.include?(e["to"])
+      end
+
+      # Build in-degree map and adjacency list
+      in_degree = nodes.each_with_object({}) { |n, h| h[n] = 0 }
+      adj = Hash.new { |h, k| h[k] = [] }
+
+      relevant_edges.each do |e|
+        # e["from"] depends on e["to"] (from has the FK pointing to to)
+        adj[e["to"]] << e["from"]
+        in_degree[e["from"]] = (in_degree[e["from"]] || 0) + 1
+      end
+
+      # First pass: standard Kahn's
+      queue = in_degree.select { |_, d| d == 0 }.keys.sort
+      sorted_nodes = []
+
+      until queue.empty?
+        node = queue.shift
+        sorted_nodes << node
+        (adj[node] || []).each do |neighbor|
+          in_degree[neighbor] -= 1
+          queue << neighbor if in_degree[neighbor] == 0
+        end
+        queue.sort!
+      end
+
+      # Find unsorted nodes
+      unsorted = nodes.reject { |n| sorted_nodes.include?(n) }
+
+      return { "sorted" => sorted_nodes, "cycles" => [] } if unsorted.empty?
+
+      cycles = find_sccs(unsorted, relevant_edges)
+
+      return { "sorted" => sorted_nodes, "cycles" => [] } if cycles.empty?
+
+      # Second pass: treat cycle nodes as resolved and re-sort remaining
+      cycle_nodes = cycles.flatten.to_set
+      still_unsorted = unsorted.reject { |n| cycle_nodes.include?(n) }
+
+      if still_unsorted.any?
+        still_set = still_unsorted.to_set
+        in_deg2 = still_unsorted.each_with_object({}) { |n, h| h[n] = 0 }
+        adj2 = Hash.new { |h, k| h[k] = [] }
+
+        relevant_edges.each do |e|
+          if still_set.include?(e["from"]) && still_set.include?(e["to"])
+            adj2[e["to"]] << e["from"]
+            in_deg2[e["from"]] = (in_deg2[e["from"]] || 0) + 1
+          end
+        end
+
+        queue2 = in_deg2.select { |_, d| d == 0 }.keys.sort
+        until queue2.empty?
+          node = queue2.shift
+          sorted_nodes << node
+          (adj2[node] || []).each do |neighbor|
+            in_deg2[neighbor] -= 1
+            queue2 << neighbor if in_deg2[neighbor] == 0
+          end
+          queue2.sort!
+        end
+      end
+
+      { "sorted" => sorted_nodes, "cycles" => cycles }
+    end
+
+    # Find a nullable FK edge in a cycle that can be deferred.
+    def self.find_deferrable_edge(cycle, edges)
+      cycle_set = cycle.to_set
+      edges.find do |e|
+        cycle_set.include?(e["from"]) &&
+          cycle_set.include?(e["to"]) &&
+          e["from"] != e["to"] &&
+          e["nullable"] == true
+      end
+    end
+
+    # Tarjan's SCC algorithm to identify exact cycles among remaining nodes.
+    def self.find_sccs(nodes, edges)
+      node_set = nodes.to_set
+      adj = Hash.new { |h, k| h[k] = [] }
+
+      edges.each do |e|
+        adj[e["to"]] << e["from"] if node_set.include?(e["from"]) && node_set.include?(e["to"])
+      end
+
+      index_counter = [0]
+      stack = []
+      on_stack = Set.new
+      indices = {}
+      lowlinks = {}
+      sccs = []
+
+      strong_connect = lambda do |v|
+        indices[v] = index_counter[0]
+        lowlinks[v] = index_counter[0]
+        index_counter[0] += 1
+        stack.push(v)
+        on_stack.add(v)
+
+        (adj[v] || []).each do |w|
+          if !indices.key?(w)
+            strong_connect.call(w)
+            lowlinks[v] = [lowlinks[v], lowlinks[w]].min
+          elsif on_stack.include?(w)
+            lowlinks[v] = [lowlinks[v], indices[w]].min
+          end
+        end
+
+        if lowlinks[v] == indices[v]
+          scc = []
+          loop do
+            w = stack.pop
+            on_stack.delete(w)
+            scc << w
+            break if w == v
+          end
+          sccs << scc if scc.length > 1
+        end
+      end
+
+      nodes.each do |node|
+        strong_connect.call(node) unless indices.key?(node)
+      end
+
+      sccs
+    end
+
+    private_class_method :find_sccs
+  end
+end

data/lib/autonoma/handler.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "set"
+
+require_relative "hmac"
+require_relative "refs"
+require_relative "errors"
+require_relative "types"
+require_relative "payload_topo"
+require_relative "schema"
+
+module Autonoma
+  module Handler
+    PROTOCOL_VERSION = begin
+      File.read(File.expand_path("../../../../protocol/version.txt", __dir__)).strip
+    rescue Errno::ENOENT, Errno::EACCES
+      "1.0"
+    end
+
+    TOKEN_RE = /\{\{\s*([^{}]+?)\s*\}\}/
+    CYCLE_RE = /\Acycle\((.*)\)\z/
+
+    def self.handle_request(config, req)
+      if config.shared_secret == config.signing_secret
+        raise Errors.same_secrets
+      end
+
+      unless config.allow_production
+        env = ENV["RAILS_ENV"] || ENV["RACK_ENV"] || ENV["RUBY_ENV"] || ENV["ENV"]
+        raise Errors.production_blocked if env == "production"
+      end
+
+      signature = req.headers["x-signature"] || req.headers["X-Signature"] || ""
+
+      unless Hmac.verify_signature(req.body, signature, config.shared_secret)
+        raise Errors.invalid_signature
+      end
+
+      begin
+        body = JSON.parse(req.body)
+      rescue JSON::ParserError
+        raise Errors.invalid_body("invalid JSON")
+      end
+
+      action = body["action"]
+      raise Errors.invalid_body("missing action") unless action
+
+      case action
+      when "discover"
+        handle_discover(config)
+      when "up"
+        handle_up(config, body)
+      when "down"
+        handle_down(config, body)
+      else
+        raise Errors.unknown_action(action)
+      end
+    rescue AutonomaError => e
+      HandlerResponse.new(status: e.status, body: { "error" => e.message, "code" => e.code })
+    rescue StandardError => e
+      HandlerResponse.new(status: 500, body: { "error" => e.message, "code" => "INTERNAL_ERROR" })
+    end
+
+    # -----------------------------------------------------------------------
+    # discover
+    # -----------------------------------------------------------------------
+
+    def self.handle_discover(config)
+      schema = Schema.build_schema_from_factories(config.factories || {}, config.scope_field)
+      HandlerResponse.new(
+        status: 200,
+        body: build_sdk_meta(config).merge("schema" => Schema.schema_to_wire(schema))
+      )
+    end
+
+    # -----------------------------------------------------------------------
+    # up
+    # -----------------------------------------------------------------------
+
+    def self.handle_up(config, body)
+      create = body["create"]
+      raise Errors.invalid_body('missing "create" in request body') unless create
+
+      test_run_id = body["testRunId"] || SecureRandom.uuid
+
+      factories = config.factories || {}
+      if factories.empty?
+        raise Errors.invalid_body(
+          "no factories registered -- every model in `create` must have a factory."
+        )
+      end
+
+      tree = PayloadTopo.resolve_payload_tree(create)
+
+      refs = {}
+      id_map = {}
+
+      # Track per-model run index for {{index}} / {{cycle()}} substitution.
+      model_index = Hash.new(0)
+
+      tree.ops.each do |op|
+        model = op.model
+        factory = factories[model]
+        if factory.nil?
+          raise Errors.invalid_body(
+            "no factory registered for model \"#{model}\". " \
+            "Register one with define_factory(...) and add it to HandlerConfig factories."
+          )
+        end
+
+        idx = model_index[model]
+        model_index[model] = idx + 1
+
+        # Substitute built-in tokens then swap temp ids for real ids.
+        resolved = resolve_tokens(op.fields, test_run_id, idx)
+        resolved = swap_temp_ids(resolved, id_map)
+
+        # Validate through the factory's input_fields.
+        validated = Schema.validate_input(resolved, factory.input_fields)
+
+        ctx = FactoryContext.new(
+          refs: refs,
+          scenario_name: test_run_id,
+          test_run_id: test_run_id
+        )
+
+        record = factory.create.call(validated, ctx)
+
+        # Normalise to hash if needed.
+        if record.respond_to?(:to_h) && !record.is_a?(Hash)
+          record = record.to_h
+        end
+
+        if !record.is_a?(Hash) || record["id"].nil?
+          raise AutonomaError.new(
+            "Factory for \"#{model}\" must return a record hash with \"id\"",
+            "FACTORY_MISSING_PK",
+            500
+          )
+        end
+
+        refs[model] = (refs[model] || []) + [record]
+        id_map[op.temp_id] = record["id"]
+      end
+
+      # Auth callback gets the first User (case-insensitive on model name).
+      auth_user = find_first_user(refs)
+      scope_value = detect_scope_value(refs, config.scope_field) || test_run_id
+      auth_context = AuthContext.new(scope_value: scope_value, refs: refs)
+      auth = config.auth.call(auth_user, auth_context)
+
+      if config.after_up
+        hook_ctx = HookContext.new(scenario_name: scope_value, refs: refs)
+        auth = config.after_up.call(hook_ctx, auth)
+      end
+
+      refs_token = Refs.sign_refs(
+        {
+          "refs" => refs,
+          "testRunId" => scope_value,
+          "environment" => "",
+          "aliasDependencies" => tree.alias_dependencies,
+          "aliasOwnerModel" => tree.alias_owner_model
+        },
+        config.signing_secret
+      )
+
+      HandlerResponse.new(
+        status: 200,
+        body: build_sdk_meta(config).merge(
+          "auth" => auth,
+          "refs" => refs,
+          "refsToken" => refs_token
+        )
+      )
+    end
+
+    # -----------------------------------------------------------------------
+    # down
+    # -----------------------------------------------------------------------
+
+    def self.handle_down(config, body)
+      refs_token = body["refsToken"]
+      raise Errors.invalid_body("missing refsToken") unless refs_token
+
+      begin
+        payload = Refs.verify_refs(refs_token, config.signing_secret)
+      rescue StandardError => e
+        raise Errors.invalid_refs_token(e.message)
+      end
+
+      refs = payload["refs"] || {}
+      test_run_id = payload["testRunId"] || ""
+      alias_deps = payload["aliasDependencies"] || {}
+      alias_owner_model = payload["aliasOwnerModel"] || {}
+
+      if config.before_down
+        hook_ctx = HookContext.new(scenario_name: test_run_id, refs: refs)
+        config.before_down.call(hook_ctx)
+      end
+
+      factories = config.factories || {}
+      teardown_order = PayloadTopo.compute_teardown_order(refs, alias_deps, alias_owner_model)
+
+      teardown_order.each do |model|
+        factory = factories[model]
+        next if factory.nil? || factory.teardown.nil?
+
+        records = refs[model] || []
+        ctx = FactoryContext.new(
+          refs: refs,
+          scenario_name: test_run_id,
+          test_run_id: test_run_id
+        )
+
+        records.reverse_each do |record|
+          factory.teardown.call(record, ctx)
+        end
+      end
+
+      HandlerResponse.new(status: 200, body: build_sdk_meta(config).merge("ok" => true))
+    end
+
+    # -----------------------------------------------------------------------
+    # helpers
+    # -----------------------------------------------------------------------
+
+    def self.build_sdk_meta(config)
+      sdk = config.sdk || {}
+      {
+        "version" => PROTOCOL_VERSION,
+        "sdk" => {
+          "language" => "ruby",
+          "orm" => sdk["orm"] || sdk[:orm] || "unknown",
+          "server" => sdk["server"] || sdk[:server] || "unknown"
+        }
+      }
+    end
+
+    # Substitute built-in tokens in field values: {{testRunId}}, {{index}},
+    # {{cycle(a,b,c)}}. Raises AutonomaError(UNRESOLVED_TOKEN) for any other
+    # {{token}}.
+    def self.resolve_tokens(value, test_run_id, index)
+      case value
+      when String
+        value.gsub(TOKEN_RE) do
+          token = Regexp.last_match(1).strip
+          if token == "testRunId"
+            test_run_id
+          elsif token == "index"
+            index.to_s
+          elsif (m = CYCLE_RE.match(token))
+            parts = m[1].split(",").map { |p| p.strip.gsub(/\A['"]|['"]\z/, "") }
+            parts.empty? ? "" : parts[index % parts.length]
+          else
+            raise AutonomaError.new(
+              "Unresolved token: {{#{token}}}",
+              "UNRESOLVED_TOKEN",
+              400
+            )
+          end
+        end
+      when Array
+        value.map { |v| resolve_tokens(v, test_run_id, index) }
+      when Hash
+        value.each_with_object({}) { |(k, v), out| out[k] = resolve_tokens(v, test_run_id, index) }
+      else
+        value
+      end
+    end
+
+    # Replace any __temp_* placeholder string with its real id.
+    def self.swap_temp_ids(value, id_map)
+      case value
+      when String
+        value.start_with?("__temp_") ? (id_map[value] || value) : value
+      when Hash
+        value.each_with_object({}) { |(k, v), out| out[k] = swap_temp_ids(v, id_map) }
+      when Array
+        value.map { |v| swap_temp_ids(v, id_map) }
+      else
+        value
+      end
+    end
+
+    def self.find_first_user(refs)
+      refs.each do |model, records|
+        normalized = model.downcase
+        return records.first if (normalized == "user" || normalized == "users") && records.any?
+      end
+      nil
+    end
+
+    def self.detect_scope_value(refs, scope_field)
+      scope_normalized = scope_field.delete("_").downcase
+      refs.each_value do |records|
+        records.each do |record|
+          record.each do |key, value|
+            return value if key.delete("_").downcase == scope_normalized && value.is_a?(String)
+          end
+        end
+      end
+      nil
+    end
+
+    private_class_method :build_sdk_meta, :handle_discover, :handle_up,
+                         :handle_down, :find_first_user, :detect_scope_value,
+                         :resolve_tokens, :swap_temp_ids
+  end
+end

data/lib/autonoma/hmac.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Autonoma
+  # Constant-time string comparison to prevent timing attacks.
+  # Shared by Hmac and Refs modules.
+  def self.secure_compare(a, b)
+    return false unless a.bytesize == b.bytesize
+
+    l = a.unpack("C*")
+    r = b.unpack("C*")
+    result = 0
+    l.each_with_index { |v, i| result |= v ^ r[i] }
+    result.zero?
+  end
+
+  module Hmac
+    # Sign a body string with a secret using HMAC-SHA256. Returns 64-char lowercase hex.
+    def self.sign_body(body, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, body)
+    end
+
+    # Verify a signature using constant-time comparison.
+    def self.verify_signature(body, signature, secret)
+      expected = sign_body(body, secret)
+      return false unless expected.length == signature.length
+
+      Autonoma.secure_compare(expected, signature)
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/autonoma/payload_topo.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Autonoma
+  module PayloadTopo
+    # Output of resolve_payload_tree.
+    class ResolvedTree
+      attr_accessor :ops, :aliases, :alias_owner_model, :alias_dependencies
+
+      def initialize
+        @ops = []
+        @aliases = {}
+        @alias_owner_model = {}
+        @alias_dependencies = {}
+      end
+    end
+
+    RESERVED_KEYS = Set.new(%w[_alias _ref]).freeze
+
+    # Walk a field value tree and append every _ref alias found.
+    def self.collect_refs(value, out)
+      case value
+      when Hash
+        ref = value["_ref"]
+        if ref.is_a?(String)
+          out << ref
+          return
+        end
+        value.each_value { |v| collect_refs(v, out) }
+      when Array
+        value.each { |v| collect_refs(v, out) }
+      end
+    end
+
+    # Replace each {"_ref": alias} with its temp id.
+    def self.resolve_refs(value, alias_to_temp_id)
+      case value
+      when Hash
+        ref = value["_ref"]
+        if ref.is_a?(String)
+          real = alias_to_temp_id[ref]
+          return real.nil? ? value : real
+        end
+        value.each_with_object({}) { |(k, v), out| out[k] = resolve_refs(v, alias_to_temp_id) }
+      when Array
+        value.map { |v| resolve_refs(v, alias_to_temp_id) }
+      else
+        value
+      end
+    end
+
+    # Topo-sort a create payload into an ordered list of CreateOp.
+    def self.resolve_payload_tree(create)
+      unless create.is_a?(Hash)
+        raise Errors.invalid_body("`create` must be an object keyed by model name")
+      end
+
+      # First pass: assign temp ids and collect alias declarations.
+      raw_entries = [] # [model, temp_id, entity, alias_name]
+      counter = 0
+      aliases = {}
+      alias_owner_model = {}
+
+      create.each do |model, entities|
+        unless entities.is_a?(Array)
+          raise Errors.invalid_body(
+            "`create.#{model}` must be a list of entity objects, got #{entities.class.name}"
+          )
+        end
+
+        entities.each do |entity|
+          unless entity.is_a?(Hash)
+            raise Errors.invalid_body(
+              "`create.#{model}` entries must be objects, got #{entity.class.name}"
+            )
+          end
+
+          temp_id = "__temp_#{model}_#{counter}"
+          counter += 1
+
+          alias_name = entity["_alias"]
+          if alias_name.is_a?(String)
+            if aliases.key?(alias_name)
+              raise Errors.invalid_body("duplicate _alias \"#{alias_name}\"")
+            end
+            aliases[alias_name] = temp_id
+            alias_owner_model[alias_name] = model
+          elsif !alias_name.nil?
+            raise Errors.invalid_body('"_alias" must be a string')
+          end
+
+          raw_entries << [model, temp_id, entity, alias_name.is_a?(String) ? alias_name : nil]
+        end
+      end
+
+      # Second pass: collect dependencies and strip reserved keys.
+      deps_by_temp_id = {}
+      fields_by_temp_id = {}
+      model_by_temp_id = {}
+      alias_by_temp_id = {}
+
+      raw_entries.each do |model, temp_id, entity, alias_name|
+        deps = []
+        cleaned = {}
+
+        entity.each do |key, value|
+          next if RESERVED_KEYS.include?(key)
+
+          collect_refs(value, deps)
+          cleaned[key] = resolve_refs(value, aliases)
+        end
+
+        unknown = deps.select { |a| !aliases.key?(a) }.uniq.sort
+        unless unknown.empty?
+          raise Errors.invalid_body(
+            "`create.#{model}` references unknown alias(es): #{unknown.join(", ")}"
+          )
+        end
+
+        deps_by_temp_id[temp_id] = deps
+        fields_by_temp_id[temp_id] = cleaned
+        model_by_temp_id[temp_id] = model
+        alias_by_temp_id[temp_id] = alias_name
+      end
+
+      # Build the temp_id graph and topo-sort.
+      in_degree = {}
+      raw_entries.each { |_, temp_id, _, _| in_degree[temp_id] = 0 }
+
+      edges = Hash.new { |h, k| h[k] = [] }
+
+      deps_by_temp_id.each do |temp_id, deps|
+        seen = Set.new
+        deps.each do |dep_alias|
+          dep_temp_id = aliases[dep_alias]
+          next if dep_temp_id == temp_id || seen.include?(dep_temp_id)
+
+          seen.add(dep_temp_id)
+          edges[dep_temp_id] << temp_id
+          in_degree[temp_id] += 1
+        end
+      end
+
+      # Kahn's, preserving payload order as the stable tie-breaker.
+      payload_order = {}
+      raw_entries.each_with_index { |(_, temp_id, _, _), idx| payload_order[temp_id] = idx }
+
+      ready = in_degree.select { |_, d| d == 0 }.keys.sort_by { |t| payload_order[t] }
+      sorted_temp_ids = []
+
+      until ready.empty?
+        tid = ready.shift
+        sorted_temp_ids << tid
+        (edges[tid] || []).each do |nxt|
+          in_degree[nxt] -= 1
+          ready << nxt if in_degree[nxt] == 0
+        end
+        ready.sort_by! { |t| payload_order[t] }
+      end
+
+      if sorted_temp_ids.length != payload_order.length
+        cycle = in_degree.select { |_, d| d > 0 }.keys.sort_by { |t| payload_order[t] }
+        cycle_models = cycle.map { |t| model_by_temp_id[t] }.join(", ")
+        raise Errors.invalid_body("cycle detected in _alias/_ref graph: #{cycle_models}")
+      end
+
+      # Build the result.
+      tree = ResolvedTree.new
+      tree.aliases = aliases
+      tree.alias_owner_model = alias_owner_model
+      tree.alias_dependencies = aliases.each_with_object({}) do |(alias_name, temp_id), h|
+        h[alias_name] = deps_by_temp_id[temp_id] || []
+      end
+
+      sorted_temp_ids.each do |tid|
+        tree.ops << CreateOp.new(
+          model: model_by_temp_id[tid],
+          fields: fields_by_temp_id[tid],
+          temp_id: tid
+        )
+      end
+
+      tree
+    end
+
+    # Order models for teardown.
+    def self.compute_teardown_order(refs, alias_dependencies, alias_owner_model)
+      models = refs.keys
+
+      if alias_dependencies.nil? || alias_dependencies.empty? ||
+         alias_owner_model.nil? || alias_owner_model.empty?
+        return models.reverse
+      end
+
+      # Build model-level dependency graph.
+      model_deps = models.each_with_object({}) { |m, h| h[m] = Set.new }
+
+      alias_dependencies.each do |alias_name, deps|
+        owner = alias_owner_model[alias_name]
+        next if owner.nil? || !model_deps.key?(owner)
+
+        deps.each do |dep_alias|
+          dep_model = alias_owner_model[dep_alias]
+          next if dep_model.nil? || dep_model == owner || !model_deps.key?(dep_model)
+
+          model_deps[owner].add(dep_model)
+        end
+      end
+
+      # Kahn's over models.
+      in_degree = models.each_with_object({}) { |m, h| h[m] = 0 }
+      adj = Hash.new { |h, k| h[k] = [] }
+
+      model_deps.each do |owner, deps|
+        deps.each do |dep_model|
+          adj[dep_model] << owner
+          in_degree[owner] += 1
+        end
+      end
+
+      payload_order = models.each_with_index.to_h
+      ready = in_degree.select { |_, d| d == 0 }.keys.sort_by { |m| payload_order[m] }
+      up_order = []
+
+      until ready.empty?
+        m = ready.shift
+        up_order << m
+        (adj[m] || []).each do |nxt|
+          in_degree[nxt] -= 1
+          ready << nxt if in_degree[nxt] == 0
+        end
+        ready.sort_by! { |m2| payload_order[m2] }
+      end
+
+      # Fall back to reversed insertion order if cycle detected (shouldn't happen).
+      return models.reverse if up_order.length != models.length
+
+      up_order.reverse
+    end
+
+    private_class_method :collect_refs, :resolve_refs
+  end
+end

data/lib/autonoma/refs.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+require "bigdecimal"
+require "date"
+require "time"
+
+module Autonoma
+  module Refs
+    # Sign a refs payload into a 3-part token string.
+    def self.sign_refs(payload, secret)
+      header = base64url_encode(JSON.generate({ alg: "HS256", typ: "REFS" }))
+      body = base64url_encode(JSON.generate(make_json_safe(payload)))
+      signature = hmac_sign("#{header}.#{body}", secret)
+      "#{header}.#{body}.#{signature}"
+    end
+
+    # Verify and decode a refs token. Returns the payload hash or raises.
+    def self.verify_refs(token, secret)
+      parts = token.split(".")
+      raise "malformed token" unless parts.length == 3
+
+      header, body, signature = parts
+      expected = hmac_sign("#{header}.#{body}", secret)
+
+      raise "signature mismatch" unless Autonoma.secure_compare(expected, signature)
+
+      JSON.parse(base64url_decode(body))
+    end
+
+    def self.base64url_encode(data)
+      data = data.encode("UTF-8") if data.is_a?(String)
+      Base64.urlsafe_encode64(data, padding: false)
+    end
+
+    def self.base64url_decode(data)
+      # Add padding back
+      padding = 4 - (data.length % 4)
+      data += "=" * padding if padding != 4
+      Base64.urlsafe_decode64(data)
+    end
+
+    def self.hmac_sign(data, secret)
+      sig = OpenSSL::HMAC.digest("SHA256", secret, data)
+      Base64.urlsafe_encode64(sig, padding: false)
+    end
+
+    # Recursively convert non-JSON-safe types (Time, DateTime, BigDecimal, etc.)
+    # to strings so that JSON.generate does not raise.
+    def self.make_json_safe(obj)
+      case obj
+      when Hash
+        obj.transform_values { |v| make_json_safe(v) }
+      when Array
+        obj.map { |v| make_json_safe(v) }
+      when Time, DateTime
+        obj.iso8601(3)
+      when Date
+        obj.iso8601
+      when BigDecimal
+        obj.to_s("F")
+      when Symbol
+        obj.to_s
+      else
+        obj
+      end
+    end
+
+    private_class_method :base64url_encode, :base64url_decode, :hmac_sign
+  end
+end

data/lib/autonoma/schema.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Autonoma
+  module Schema
+    VALID_TYPES = Set.new(%w[string integer number boolean timestamp date uuid json]).freeze
+
+    # Map a Ruby type string to the SDK's coarse type string.
+    def self.field_type_from_class(type_str)
+      return "string" if type_str.nil?
+
+      normalized = type_str.to_s.downcase
+      VALID_TYPES.include?(normalized) ? normalized : "string"
+    end
+
+    # Convert CamelCase to snake_case for cosmetic tableName.
+    def self.camel_to_snake(name)
+      out = []
+      name.each_char.with_index do |ch, i|
+        if ch =~ /[A-Z]/ && i > 0 && name[i - 1] !~ /[A-Z]/
+          out << "_"
+        end
+        out << ch.downcase
+      end
+      out.join
+    end
+
+    # Build field list from input_fields array.
+    # Each entry is a hash with :name, :type, :required keys.
+    def self.fields_from_input_fields(input_fields)
+      fields = [
+        FieldInfo.new(
+          name: "id",
+          type: "string",
+          is_required: false,
+          is_id: true,
+          has_default: true
+        )
+      ]
+
+      (input_fields || []).each do |f|
+        name = f[:name] || f["name"]
+        type = f[:type] || f["type"]
+        required = f[:required].nil? ? f["required"] : f[:required]
+
+        fields << FieldInfo.new(
+          name: name.to_s,
+          type: field_type_from_class(type),
+          is_required: !!required,
+          is_id: false,
+          has_default: !required
+        )
+      end
+
+      fields
+    end
+
+    # Build the SDK's discover-time schema from registered factories.
+    def self.build_schema_from_factories(factories, scope_field)
+      models = []
+
+      (factories || {}).each do |entity, factory|
+        if factory.input_fields.nil? || factory.input_fields.empty?
+          raise ArgumentError,
+                "Factory \"#{entity}\" has no input_fields. " \
+                "Every factory must declare input_fields in define_factory(...)."
+        end
+
+        models << ModelInfo.new(
+          name: entity,
+          table_name: camel_to_snake(entity),
+          fields: fields_from_input_fields(factory.input_fields)
+        )
+      end
+
+      SchemaInfo.new(
+        models: models,
+        edges: [],
+        relations: [],
+        scope_field: scope_field
+      )
+    end
+
+    # Serialise a SchemaInfo to the JSON shape the dashboard expects.
+    def self.schema_to_wire(schema)
+      {
+        "models" => schema.models.map do |m|
+          {
+            "name" => m.name,
+            "tableName" => m.table_name,
+            "fields" => m.fields.map do |f|
+              {
+                "name" => f.name,
+                "type" => f.type,
+                "isRequired" => f.is_required,
+                "isId" => f.is_id,
+                "hasDefault" => f.has_default
+              }
+            end
+          }
+        end,
+        "edges" => schema.edges.map do |e|
+          {
+            "from" => e.from_model,
+            "to" => e.to_model,
+            "localField" => e.local_field,
+            "foreignField" => e.foreign_field,
+            "nullable" => e.nullable
+          }
+        end,
+        "relations" => schema.relations.map do |r|
+          {
+            "parentModel" => r.parent_model,
+            "childModel" => r.child_model,
+            "parentField" => r.parent_field,
+            "childField" => r.child_field
+          }
+        end,
+        "scopeField" => schema.scope_field
+      }
+    end
+
+    # Validate input fields hash: strip unknown keys, check required fields.
+    def self.validate_input(fields, input_fields)
+      known_names = Set.new
+      required_names = []
+
+      (input_fields || []).each do |f|
+        name = (f[:name] || f["name"]).to_s
+        known_names.add(name)
+        req = f[:required].nil? ? f["required"] : f[:required]
+        required_names << name if req
+      end
+
+      # Strip unknown keys
+      validated = fields.select { |k, _| known_names.include?(k.to_s) }
+
+      # Check required fields
+      missing = required_names.select { |name| !validated.key?(name) && !validated.key?(name.to_sym) }
+      unless missing.empty?
+        raise Errors.invalid_body("missing required fields: #{missing.join(", ")}")
+      end
+
+      validated
+    end
+
+    private_class_method :camel_to_snake, :fields_from_input_fields
+  end
+end

data/lib/autonoma/types.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Autonoma
+  FieldInfo = Struct.new(:name, :type, :is_required, :is_id, :has_default, keyword_init: true)
+  ModelInfo = Struct.new(:name, :table_name, :fields, keyword_init: true)
+
+  FKEdge = Struct.new(:from_model, :to_model, :local_field, :foreign_field, :nullable, keyword_init: true)
+
+  SchemaRelation = Struct.new(:parent_model, :child_model, :parent_field, :child_field, keyword_init: true)
+
+  SchemaInfo = Struct.new(:models, :edges, :relations, :scope_field, keyword_init: true)
+
+  CreateOp = Struct.new(:model, :fields, :temp_id, keyword_init: true)
+
+  HandlerRequest = Struct.new(:body, :headers, keyword_init: true) do
+    def initialize(body:, headers: {})
+      super
+    end
+  end
+
+  HandlerResponse = Struct.new(:status, :body, keyword_init: true)
+
+  HookContext = Struct.new(:scenario_name, :refs, keyword_init: true)
+  AuthContext = Struct.new(:scope_value, :refs, keyword_init: true)
+
+  FactoryContext = Struct.new(:refs, :scenario_name, :test_run_id, keyword_init: true)
+
+  FactoryDefinition = Struct.new(:create, :teardown, :input_fields, keyword_init: true)
+
+  HandlerConfig = Struct.new(
+    :scope_field,
+    :shared_secret,
+    :signing_secret,
+    :allow_production,
+    :auth,
+    :sdk,
+    :before_down,
+    :after_up,
+    :factories,
+    keyword_init: true
+  ) do
+    def initialize(scope_field:, shared_secret:, signing_secret:, auth:,
+                   allow_production: false, sdk: nil,
+                   before_down: nil, after_up: nil, factories: nil)
+      super
+    end
+  end
+end

data/lib/autonoma.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "autonoma/errors"
+require_relative "autonoma/types"
+require_relative "autonoma/hmac"
+require_relative "autonoma/refs"
+require_relative "autonoma/graph"
+require_relative "autonoma/fingerprint"
+require_relative "autonoma/payload_topo"
+require_relative "autonoma/schema"
+require_relative "autonoma/factory"
+require_relative "autonoma/handler"
+
+module Autonoma
+  VERSION = "0.2.0"
+end

data/lib/autonoma_rails/server.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "autonoma"
+
+module AutonomaRails
+  # Rails controller mixin for handling Autonoma protocol requests.
+  #
+  # Usage in a Rails controller:
+  #
+  #   class AutonomaController < ApplicationController
+  #     include AutonomaRails::Handler
+  #
+  #     skip_before_action :verify_authenticity_token
+  #
+  #     def handle
+  #       autonoma_handle(autonoma_config)
+  #     end
+  #
+  #     private
+  #
+  #     def autonoma_config
+  #       @autonoma_config ||= Autonoma::HandlerConfig.new(
+  #         scope_field: "organizationId",
+  #         shared_secret: ENV["AUTONOMA_SHARED_SECRET"],
+  #         signing_secret: ENV["AUTONOMA_SIGNING_SECRET"],
+  #         auth: ->(user, ctx) { { "token" => "..." } },
+  #         factories: { "User" => Autonoma::Factory.define_factory(...) }
+  #       )
+  #     end
+  #   end
+  #
+  module Handler
+    def autonoma_handle(config)
+      enriched = config.dup
+      sdk = (enriched.sdk || {}).merge("server" => "rails")
+      enriched.sdk = sdk
+
+      body_str = request.raw_post
+      headers = request.headers.to_h
+        .select { |k, _| k.is_a?(String) }
+        .transform_keys(&:downcase)
+
+      req = Autonoma::HandlerRequest.new(body: body_str, headers: headers)
+      result = Autonoma::Handler.handle_request(enriched, req)
+
+      render json: Autonoma::Refs.make_json_safe(result.body), status: result.status
+    end
+  end
+
+  # Rack middleware alternative for mounting Autonoma as a Rack app.
+  class Middleware
+    def initialize(app, config, path: "/api/autonoma")
+      @app = app
+      @config = enrich_config(config)
+      @path = path
+    end
+
+    def call(env)
+      unless env["PATH_INFO"] == @path && env["REQUEST_METHOD"] == "POST"
+        return @app.call(env)
+      end
+
+      body_str = env["rack.input"].read
+      env["rack.input"].rewind
+
+      headers = {}
+      env.each do |key, value|
+        if key.start_with?("HTTP_")
+          header_name = key[5..].downcase.tr("_", "-")
+          headers[header_name] = value
+        end
+      end
+      headers["content-type"] = env["CONTENT_TYPE"] if env["CONTENT_TYPE"]
+
+      req = Autonoma::HandlerRequest.new(body: body_str, headers: headers)
+      result = Autonoma::Handler.handle_request(@config, req)
+
+      [
+        result.status,
+        { "Content-Type" => "application/json" },
+        [JSON.generate(Autonoma::Refs.make_json_safe(result.body))]
+      ]
+    end
+
+    private
+
+    def enrich_config(config)
+      enriched = config.dup
+      sdk = (enriched.sdk || {}).merge("server" => "rails")
+      enriched.sdk = sdk
+      enriched
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: autonoma-ai
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Autonoma AI
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Ruby SDK for the Autonoma Environment Factory. Handles HMAC verification,
+  JWT refs, template resolution, factory-driven entity creation, and scoped teardown.
+email:
+- eng@autonoma.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/autonoma.rb
+- lib/autonoma/errors.rb
+- lib/autonoma/factory.rb
+- lib/autonoma/fingerprint.rb
+- lib/autonoma/graph.rb
+- lib/autonoma/handler.rb
+- lib/autonoma/hmac.rb
+- lib/autonoma/payload_topo.rb
+- lib/autonoma/refs.rb
+- lib/autonoma/schema.rb
+- lib/autonoma/types.rb
+- lib/autonoma_rails/server.rb
+homepage: https://autonoma.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://autonoma.ai
+  source_code_uri: https://github.com/Autonoma-AI/sdk
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Autonoma SDK — automate the Autonoma Environment Factory endpoint
+test_files: []