odin-foundation 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a42b39245e4ab2f8821e0e12100d16418316b22758071d7acf28db0b7a754f20
-  data.tar.gz: 99f7bc6624af35e90864f3ccc1239eb2c3c8ab1cd1a50bcd5daffdca36655e98
+  metadata.gz: 7941332bc111a6e015c111bdacc0112a4de7158790df8dc5795846261d63c90f
+  data.tar.gz: 2925314fb92f73c7a2f83cfde86a0975a619c9ac9f88186aeffbcfdb29f2c587
 SHA512:
-  metadata.gz: 00027a7160bb7e6605bdbb3e77e2ea54232147902027cdc98d3dccc6b6ce06635563d4ca84698a12a3325d29b1310e88355911dcd0c75099ad13ba35eef84a64
-  data.tar.gz: 4ad5366860defb9e19affa8f666eccd4d3d6bd3a9cba539131bb189987c9b878a6217cb60260bb58ff03660e71d4bb3865eb77fed4bb4ff47a3e01124f4621fb
+  metadata.gz: 07ebdd4410ca462bcc14fb2095ac1302b8aecbe06a32e069bdd9c2bd3ce08afdf0fb5653f319d347fcdbcfd59a5b8338e28b718e4eb9e77dc42c145b53e586c6
+  data.tar.gz: 67dad1314b2884092d7eafa3667e4815a2469ff94f9ec4c0870a49eb0c4701d28e94d32617e3d820d59327d6eb87583bdf7b0914011ea809ce657ff4bb5e3e4a

data/lib/odin/transform/transform_engine.rb

@@ -6,6 +6,19 @@ module Odin
       # Verb registry — populated in Phase 9-10. For now, core verbs only.
       CORE_VERBS = {}.freeze
 
+      # Verbs whose cost grows with an array argument. Charged proportional to
+      # the array width so large-array work cannot escape the fuel budget.
+      SORT_VERBS = %w[sort].freeze
+      WIDTH_VERBS = %w[
+        distinct groupBy keyBy countBy reduce
+        sum avg min max count sumIf avgIf countIf
+        union intersection difference symmetricDifference
+        map filter window explode flatten reverse
+      ].freeze
+
+      # Read the wall clock once per this many charged units.
+      CLOCK_CHECK_INTERVAL = 1024
+
       class TransformError < StandardError
         attr_reader :code
         attr_accessor :segment, :field
@@ -43,9 +56,20 @@ module Odin
         end
       end
 
+      # Execution guard abort (fuel, timeout, or depth). Not downgraded by the
+      # onError policy; the execute boundary surfaces it as a failed result.
+      class TransformAbortError < StandardError
+        attr_reader :transform_error
+
+        def initialize(transform_error)
+          @transform_error = transform_error
+          super(transform_error.message)
+        end
+      end
+
       # ── Transform Error Codes ──
-      # T001-T010 are reserved for core transform errors.
-      # T011+ are for implementation-specific errors.
+      # T001-T018 are reserved for core transform errors.
+      # Later codes are for implementation-specific errors.
       module ErrorCodes
         T001_UNKNOWN_VERB            = "T001"
         T002_INVALID_VERB_ARGS       = "T002"
@@ -60,6 +84,33 @@ module Odin
         T011_INCOMPATIBLE_CONVERSION = "T011"
         T012_DANGLING_BRANCH         = "T012"
         T014_NESTED_INTERPOLATION    = "T014"
+        T016_TRANSFORM_BUDGET_EXCEEDED  = "T016"
+        T017_TRANSFORM_TIMEOUT_EXCEEDED = "T017"
+        T018_EXPRESSION_DEPTH_EXCEEDED  = "T018"
+      end
+
+      # Create a T016 Transform Budget Exceeded error.
+      def self.budget_exceeded_error(limit)
+        TransformError.new(
+          "Transform fuel budget exceeded (limit #{limit})",
+          code: ErrorCodes::T016_TRANSFORM_BUDGET_EXCEEDED
+        )
+      end
+
+      # Create a T017 Transform Timeout Exceeded error.
+      def self.timeout_exceeded_error(limit_ms)
+        TransformError.new(
+          "Transform timeout exceeded (limit #{limit_ms}ms)",
+          code: ErrorCodes::T017_TRANSFORM_TIMEOUT_EXCEEDED
+        )
+      end
+
+      # Create a T018 Expression Depth Exceeded error.
+      def self.expression_depth_exceeded_error(limit)
+        TransformError.new(
+          "Expression evaluation depth exceeded (limit #{limit})",
+          code: ErrorCodes::T018_EXPRESSION_DEPTH_EXCEEDED
+        )
       end
 
       # Create a T014 Nested Interpolation error.
@@ -132,9 +183,24 @@ module Odin
 
       def initialize
         @verb_registry = build_verb_registry
+        reset_guard!
+      end
+
+      # Reset execution-guard state for a single execute call. Fuel and timeout
+      # charge only when their cap is set (> 0); depth uses its standing default.
+      def reset_guard!
+        @fuel_cap = Utils::SecurityLimits.max_transform_fuel
+        @timeout_ms = Utils::SecurityLimits.transform_timeout_ms
+        @max_expr_depth = Utils::SecurityLimits.max_expression_depth
+        @fuel_used = 0
+        @expr_depth = 0
+        @ops_since_clock = 0
+        @start_time = @timeout_ms.positive? ? monotonic_ms : 0
       end
 
       def execute(transform_def, source_data, import_resolver: nil)
+        reset_guard!
+
         # Merge imported tables, constants, accumulators, and segments.
         if import_resolver && transform_def.imports && !transform_def.imports.empty?
           resolve_imports(transform_def, import_resolver)
@@ -159,23 +225,27 @@ module Odin
 
         # 3. Process segments (multi-pass support)
         output = {}
-        passes = transform_def.passes
-        if passes.empty?
-          # Single implicit pass
-          process_segment_list(transform_def.segments, source, context, output)
-        else
-          # Multi-pass: explicit passes first, then pass-0 (implicit)
-          all_passes = passes.include?(0) ? passes : passes + [0]
-          first_pass = true
-          all_passes.each do |pass_num|
-            unless first_pass
-              reset_non_persist_accumulators(context, transform_def.accumulators)
-            end
-            first_pass = false
+        begin
+          passes = transform_def.passes
+          if passes.empty?
+            # Single implicit pass
+            process_segment_list(transform_def.segments, source, context, output)
+          else
+            # Multi-pass: explicit passes first, then pass-0 (implicit)
+            all_passes = passes.include?(0) ? passes : passes + [0]
+            first_pass = true
+            all_passes.each do |pass_num|
+              unless first_pass
+                reset_non_persist_accumulators(context, transform_def.accumulators)
+              end
+              first_pass = false
 
-            pass_segments = transform_def.segments.select { |s| (s.pass || 0) == pass_num }
-            process_segment_list(pass_segments, source, context, output)
+              pass_segments = transform_def.segments.select { |s| (s.pass || 0) == pass_num }
+              process_segment_list(pass_segments, source, context, output)
+            end
           end
+        rescue TransformAbortError => e
+          return abort_result(e, output, context)
         end
 
         # 4. Apply confidential enforcement
@@ -229,44 +299,48 @@ module Odin
         end
 
         # Process each record/line
-        lines = raw_input.split(/[\r\n]+/)
-        lines.each do |line|
-          next if line.strip.empty?
+        begin
+          lines = raw_input.split(/[\r\n]+/)
+          lines.each do |line|
+            next if line.strip.empty?
 
-          disc_value = extract_discriminator_value(line, disc, delimiter)
-          segment = segment_map[disc_value]
-          next unless segment
+            disc_value = extract_discriminator_value(line, disc, delimiter)
+            segment = segment_map[disc_value]
+            next unless segment
 
-          record_source = parse_record(line, source_format, delimiter)
-          record_output = {}
+            record_source = parse_record(line, source_format, delimiter)
+            record_output = {}
 
-          # Set the record as the current source for path resolution
-          context.source = record_source
+            # Set the record as the current source for path resolution
+            context.source = record_source
 
-          # Process field mappings
-          segment.field_mappings.each do |mapping|
-            process_mapping(mapping, record_source, context, record_output)
-          end
+            # Process field mappings
+            segment.field_mappings.each do |mapping|
+              process_mapping(mapping, record_source, context, record_output)
+            end
 
-          # Process children
-          segment.children.each do |child|
-            process_segment(child, record_source, context, record_output)
-          end
+            # Process children
+            segment.children.each do |child|
+              process_segment(child, record_source, context, record_output)
+            end
 
-          # Merge into output
-          seg_name = segment.name
+            # Merge into output
+            seg_name = segment.name
 
-          if segment.is_array
-            array_accumulators[seg_name] ||= []
-            array_accumulators[seg_name] << record_output
-          else
-            # Merge fields into existing segment object
-            if output[seg_name].is_a?(Hash)
-              record_output.each { |k, v| output[seg_name][k] = v }
+            if segment.is_array
+              array_accumulators[seg_name] ||= []
+              array_accumulators[seg_name] << record_output
             else
-              output[seg_name] = record_output
+              # Merge fields into existing segment object
+              if output[seg_name].is_a?(Hash)
+                record_output.each { |k, v| output[seg_name][k] = v }
+              else
+                output[seg_name] = record_output
+              end
             end
           end
+        rescue TransformAbortError => e
+          return abort_result(e, output, context)
         end
 
         # Merge array accumulators into output in segment order
@@ -391,9 +465,84 @@ module Odin
         end
       end
 
+      # ── Execution Guard ──
+
+      # Surface a guard abort as a failed result; the abort is never raised past
+      # the execute boundary. The guard error joins context.errors so the result
+      # reports failure.
+      def abort_result(err, output, context)
+        context.errors << err.transform_error
+        plain_output = deep_to_ruby(output)
+        TransformResult.new(output: plain_output, formatted: "", errors: context.errors, warnings: context.warnings)
+      end
+
+      # Monotonic clock in milliseconds for the wall-clock guard.
+      def monotonic_ms
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
+      end
+
+      # Charge fuel and, at a coarse interval, the wall clock. Both are no-ops
+      # unless their cap is set (> 0), so unbounded transforms pay nothing.
+      def charge(units)
+        if @fuel_cap.positive?
+          @fuel_used += units
+          raise TransformAbortError.new(self.class.budget_exceeded_error(@fuel_cap)) if @fuel_used > @fuel_cap
+        end
+        return unless @timeout_ms.positive?
+
+        @ops_since_clock += units
+        return if @ops_since_clock < CLOCK_CHECK_INTERVAL
+
+        @ops_since_clock = 0
+        return unless monotonic_ms - @start_time > @timeout_ms
+
+        raise TransformAbortError.new(self.class.timeout_exceeded_error(@timeout_ms))
+      end
+
+      # Charge width for a verb doing O(n)/O(n log n) work over an array argument,
+      # so large-array work cannot escape the budget at a flat unit. Runs when
+      # fuel OR timeout is set, so a timeout-only host can interrupt wide verbs.
+      def charge_verb_width(verb, args)
+        return if @fuel_cap <= 0 && @timeout_ms <= 0
+
+        n = first_array_width(args)
+        return if n <= 0
+
+        if SORT_VERBS.include?(verb)
+          charge(n * Math.log2([n, 2].max).ceil)
+        elsif WIDTH_VERBS.include?(verb)
+          charge(n)
+        end
+      end
+
+      # Width of the first array-typed argument, or 0 if none.
+      def first_array_width(args)
+        args.each do |arg|
+          return arg.value.length if arg.is_a?(Types::DynValue) && arg.array?
+        end
+        0
+      end
+
       # ── Expression Evaluation ──
 
+      # Guard boundary: enforce depth, charge one base unit of fuel, and batch the
+      # wall-clock check before delegating to the evaluator. All evaluation paths
+      # funnel through here, so charging stays concentrated at this single point.
       def evaluate(expr, context)
+        @expr_depth += 1
+        if @expr_depth > @max_expr_depth
+          @expr_depth -= 1
+          raise TransformAbortError.new(self.class.expression_depth_exceeded_error(@max_expr_depth))
+        end
+        charge(1)
+        begin
+          evaluate_inner(expr, context)
+        ensure
+          @expr_depth -= 1
+        end
+      end
+
+      def evaluate_inner(expr, context)
         case expr
         when LiteralExpr
           val = expr.value
@@ -1111,6 +1260,8 @@ module Odin
         if target.start_with?("_")
           begin
             evaluate(mapping.expression, context)
+          rescue TransformAbortError
+            raise
           rescue StandardError => e
             context.errors << TransformError.new(e.message)
           end
@@ -1227,6 +1378,9 @@ module Odin
           # Store DynValue directly to preserve type information (date, timestamp, etc.)
           dv_val = val.is_a?(Types::DynValue) ? val : Types::DynValue.from_ruby(val)
           set_path(output, target, dv_val)
+        rescue TransformAbortError
+          # Guard aborts are not downgraded by onError.
+          raise
         rescue CodedTransformError => e
           # Coded errors carry a stable T-code; preserve it under fail/warn.
           coded = e.transform_error
@@ -1555,6 +1709,7 @@ module Odin
           end
           val
         end
+        charge_verb_width(verb_name, evaluated_args)
 
         # Special handling for accumulate/set
         case verb_name
@@ -1589,6 +1744,7 @@ module Odin
 
         # Eager evaluation for all other verbs
         evaluated_args = args.map { |arg| evaluate(arg, context) }
+        charge_verb_width(verb_name, evaluated_args)
 
         # Special handling for accumulate/set
         case verb_name

data/lib/odin/types/schema.rb

@@ -154,11 +154,12 @@ module Odin
     # Schema type definition (named object structure)
     class SchemaType
       attr_reader :name, :fields, :namespace, :composition,
-                  :base_type, :constraints, :intersection_types, :parent_types
+                  :base_type, :constraints, :intersection_types, :parent_types,
+                  :arrays
 
       def initialize(name:, fields: {}, namespace: nil, composition: nil,
                      base_type: nil, constraints: nil, intersection_types: nil,
-                     parent_types: nil)
+                     parent_types: nil, arrays: {})
         @name = name.freeze
         @fields = fields.freeze
         @namespace = namespace&.freeze
@@ -167,22 +168,27 @@ module Odin
         @constraints = (constraints || {}).freeze
         @intersection_types = intersection_types&.freeze
         @parent_types = parent_types&.freeze
+        # Array-of-object entries declared inside the type, keyed by array name.
+        @arrays = (arrays || {}).freeze
         freeze
       end
     end
 
     # Schema array definition
     class SchemaArray
-      attr_reader :path, :item_fields, :min_items, :max_items, :unique, :columns
+      attr_reader :path, :item_fields, :min_items, :max_items, :unique, :columns,
+                  :item_type_ref
 
       def initialize(path:, item_fields: {}, min_items: nil, max_items: nil,
-                     unique: false, columns: nil)
+                     unique: false, columns: nil, item_type_ref: nil)
         @path = path.freeze
         @item_fields = item_fields.freeze
         @min_items = min_items
         @max_items = max_items
         @unique = unique
         @columns = columns&.freeze
+        # For an `arr[] = @type` declaration, the entry fields come from this type.
+        @item_type_ref = item_type_ref&.freeze
         freeze
       end
     end

data/lib/odin/utils/security_limits.rb

@@ -12,6 +12,32 @@ module Odin
       MAX_RECORDS             = 100_000
       MAX_ASSIGNMENTS         = 100_000
       MAX_REGEX_PATTERN_LENGTH = 500
+      MAX_EXPRESSION_DEPTH    = 32
+
+      # Read an integer limit from ODIN_<name>, falling back to default.
+      def self.env_int(name, default)
+        raw = ENV["ODIN_#{name}"]
+        return default if raw.nil? || raw.strip.empty?
+
+        Integer(raw)
+      rescue ArgumentError
+        default
+      end
+
+      # Transform fuel budget; 0 = unbounded.
+      def self.max_transform_fuel
+        env_int("MAX_TRANSFORM_FUEL", 0)
+      end
+
+      # Transform wall-clock timeout in milliseconds; 0 = unbounded.
+      def self.transform_timeout_ms
+        env_int("TRANSFORM_TIMEOUT_MS", 0)
+      end
+
+      # Expression evaluation depth cap; standing default when unset.
+      def self.max_expression_depth
+        env_int("MAX_EXPRESSION_DEPTH", MAX_EXPRESSION_DEPTH)
+      end
     end
   end
 end

data/lib/odin/validation/schema_parser.rb

@@ -73,6 +73,8 @@ module Odin
           end
         end
 
+        extract_type_arrays
+
         Types::OdinSchema.new(
           metadata: @metadata,
           types: @types,
@@ -83,6 +85,62 @@ module Odin
         )
       end
 
+      # Pull array-of-object entry fields out of each type's flat field map. A key
+      # `arr[]` (whose value is a type reference) becomes an array with an entry
+      # type ref; keys `arr[].field` become an array whose item fields are those
+      # fields. Matching keys are removed from the type's fields.
+      def extract_type_arrays
+        @types.each do |type_name, type|
+          builders = {}
+          remaining_fields = {}
+
+          type.fields.each do |key, field|
+            m = key.match(/\A([^\[\]]+)\[\](?:\.(.+))?\z/)
+            unless m
+              remaining_fields[key] = field
+              next
+            end
+
+            arr_name = m[1]
+            item_path = m[2]
+            b = builders[arr_name] ||= { item_fields: {}, item_type_ref: nil }
+
+            if item_path.nil?
+              # arr[] = @type  -> entry fields come from the referenced type
+              ref = field.type_ref
+              b[:item_type_ref] = ref if ref && ref != "array"
+            else
+              # arr[].item_path = field
+              b[:item_fields][item_path] = field
+            end
+          end
+
+          next if builders.empty?
+
+          arrays = {}
+          builders.each do |arr_name, b|
+            arrays[arr_name] = Types::SchemaArray.new(
+              path: arr_name,
+              item_fields: b[:item_fields],
+              unique: false,
+              item_type_ref: b[:item_type_ref]
+            )
+          end
+
+          @types[type_name] = Types::SchemaType.new(
+            name: type.name,
+            fields: remaining_fields,
+            namespace: type.namespace,
+            composition: type.composition,
+            base_type: type.base_type,
+            constraints: type.constraints,
+            intersection_types: type.intersection_types,
+            parent_types: type.parent_types,
+            arrays: arrays
+          )
+        end
+      end
+
       private
 
       def parse_import(line)
@@ -453,6 +511,8 @@ module Odin
         end
 
         field_name = left
+        # Keep the raw left side so a type can retain its `[]` array markers.
+        raw_field_name = left
         # Strip array indicator from field names
         is_array_field = field_name.end_with?("[]")
         field_name = field_name[0...-2] if is_array_field
@@ -481,15 +541,20 @@ module Odin
         # Parse the field spec from the right side
         schema_field = parse_field_spec(full_path, right)
 
-        # Override type_ref for array fields
+        # Override type_ref for array fields. Inside a type, keep an entry type
+        # ref (arr[] = @entry) so it can be extracted into the type's arrays map.
         if is_array_field
+          array_type_ref = "array"
+          if @current_header_kind == :type && schema_field.type_ref
+            array_type_ref = schema_field.type_ref
+          end
           schema_field = Types::SchemaField.new(
             name: schema_field.name, field_type: schema_field.field_type,
             required: schema_field.required, nullable: schema_field.nullable,
             redacted: schema_field.redacted, deprecated: schema_field.deprecated,
             constraints: schema_field.constraints, conditionals: schema_field.conditionals,
             computed: schema_field.computed, immutable: schema_field.immutable,
-            type_ref: "array"
+            type_ref: array_type_ref
           )
         end
 
@@ -499,8 +564,10 @@ module Odin
           if @current_type_name && @types[@current_type_name]
             old_type = @types[@current_type_name]
             new_fields = old_type.fields.dup
+            # Keep `[]` markers so array-of-object entries can be extracted later.
+            key_name = raw_field_name
             # Relative sub-section ({.term}) prefixes the field key (e.g. term.effective)
-            type_key = @current_type_sub_path.empty? ? field_name : "#{@current_type_sub_path}.#{field_name}"
+            type_key = @current_type_sub_path.empty? ? key_name : "#{@current_type_sub_path}.#{key_name}"
             new_fields[type_key] = schema_field
             @types[@current_type_name] = Types::SchemaType.new(
               name: old_type.name,

data/lib/odin/validation/validator.rb

@@ -201,10 +201,14 @@ module Odin
       # A field typed @SomeType enforces that type's required fields under the field
       # path, but only when the sub-object is present (or the field itself required).
       def check_field_typeref_required_fields
-        @schema.fields.each do |path, field|
-          next if path.end_with?("._composition")
+        @schema.fields.each do |raw_path, field|
+          next if raw_path.end_with?("._composition")
           next unless field.type_ref
 
+          # A field under the root {} header keys as ".field"; the document path
+          # has no leading dot.
+          path = raw_path.sub(/\A\./, "")
+
           member_names(field.type_ref).each do |member|
             type = lookup_type(member)
             next unless type
@@ -226,8 +230,66 @@ module Odin
                 expected: "present"
               )
             end
+
+            check_type_array_required_fields(path, type) if present
+          end
+        end
+      end
+
+      # Expand a referenced type's array-of-object entries under each present
+      # index so entry-level required markers fire only when the entry is present.
+      def check_type_array_required_fields(path, type)
+        return if type.arrays.nil? || type.arrays.empty?
+
+        type.arrays.each do |arr_name, schema_array|
+          item_fields = resolve_array_item_fields(schema_array)
+          next if item_fields.empty?
+
+          array_path = "#{path}.#{arr_name}"
+          present_array_indices(array_path).each do |idx|
+            item_fields.each do |fname, tfield|
+              next if fname == "_composition"
+              next unless tfield.required
+              next if tfield.computed
+
+              full = "#{array_path}[#{idx}].#{fname}"
+              next if doc_has_value?(full)
+
+              add_error(
+                code: Errors::ValidationErrorCode::REQUIRED_FIELD_MISSING,
+                path: full,
+                message: "Required field '#{full}' is missing",
+                expected: "present"
+              )
+            end
+          end
+        end
+      end
+
+      # Entry fields for an array: inline item fields, or the fields of the type
+      # named by item_type_ref (for the arr[] = @type form).
+      def resolve_array_item_fields(schema_array)
+        return schema_array.item_fields unless schema_array.item_fields.empty?
+
+        if schema_array.item_type_ref
+          member_names(schema_array.item_type_ref).each do |member|
+            type = lookup_type(member)
+            return type.fields if type
           end
         end
+        schema_array.item_fields
+      end
+
+      # Distinct indices present in the document under the given array path.
+      def present_array_indices(array_path)
+        seen = {}
+        prefix = "#{array_path}["
+        @doc.paths.each do |p|
+          next unless p.start_with?(prefix)
+          m = p[array_path.length..].match(/\A\[(\d+)\]/)
+          seen[m[1].to_i] = true if m
+        end
+        seen.keys.sort
       end
 
       # Split an &-joined type_ref (e.g. "@hasName&hasAge") into bare member names.

data/lib/odin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Odin
-  VERSION = "1.2.0"
+  VERSION = "1.2.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: odin-foundation
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.2
 platform: ruby
 authors:
 - ODIN Foundation
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-03 00:00:00.000000000 Z
+date: 2026-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal