axn 0.1.0.pre.alpha.5 → 0.1.0.pre.alpha.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c950f2b3d95c1f76aa0d963531b635e08c57058a2c3e2c8d07ccd40355faa5
-  data.tar.gz: 459ab003e2d8802c4c547ff6b89f6de3cc673e7e50072a66928d6a1b78444db7
+  metadata.gz: 3ff42be650685edfd89fd7ca703ea34d6f216caa0f2b1bcb1c6f1d939f5be32b
+  data.tar.gz: 3b99fe3510d0db9d62e159c41aa54572b709bfef8425422746ae1b57516c1fec
 SHA512:
-  metadata.gz: b8917cfa50c90daf33a41ebc40c90e5bec9bafe926da10a70ac4b73c34d5883185569af921d8f7693dd4f0b38074d07d675ecc8d3f7b4808be4b69ef8e52c6b9
-  data.tar.gz: 96a0838272f6f800206d2c85beae9c82f1e1ef954db7d940d856c431719870639bc4e63f1ad1883621665ac67eaa676bbc270c1072c0bf517d458e268d6790ef
+  metadata.gz: c41fc0bf24b4ed5ee67d4c1e43e7d64fe661800c0aac87c3096b80f50707871446a9d844ee4bc54e66992b6fa7980c7d58dcd5d1e238a566c87610b1c62dbad5
+  data.tar.gz: e4603c1d65cf9cd152a329faa6f53764a25b39ecc8c96129f067e3c0e5000925412e30d2801d2bc33b0be299e9c15271d4eb6f8507f2726339e97f72f1c585e6

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.1.0-alpha.5.1
+
+* [BUGFIX] The Rails engine now registers even when `axn` is required before Rails. `require "axn"` loaded `axn/rails/engine` only if `Rails` was already defined, and re-requiring axn later is a no-op — so a host whose `spec_helper.rb` requires `axn/testing/spec_helpers` (the placement we document) ahead of the `rails_helper.rb` that boots the app got no engine at all. Without it `app/actions` never received its configured `app_actions_autoload_namespace`, Rails pushed the directory at the root namespace instead, and every constant under it was unresolvable — in the test environment only, so a passing boot said nothing. Introduced in 0.1.0-alpha.5, when `axn/testing/spec_helpers` began requiring `axn/testing` (and through it the full gem). The engine load is now deferred to `ActiveSupport.on_load(:before_configuration)` when Rails is absent at require time.
+
+### Performance
+
+* [INTERNAL] The one-off ActiveModel validator class for a declared field/subfield is now compiled once per class and reused across every `.call`, instead of being recompiled (and its ActiveModel validator machinery re-instantiated) on every call. `auto_log` no longer builds its before/after payload when the configured logger's own severity level would discard it. `_model_fields` and `_declared_fields` are now cached per class instead of being rebuilt from the full contract on every reader definition / every read. Recovers roughly half of alpha-5's per-call allocation increase on the `basic` benchmark scenario — 489 → 250 objects/call (see PRO-3050).
+* [BREAKING] `Result#declared_fields` now returns a frozen Array. Previously each call built a fresh Array, so appending to the one handed to a given result had no effect beyond that call; the Array is now cached and shared across every call of the class (see above), so mutating it raises `FrozenError` instead of silently being a no-op.
+
 ## 0.1.0-alpha.5
 
 Most of what follows announces itself: a new option, a rename, or a declaration error you now get at class definition instead of on every call. These are the changes that do **not** — re-run your suite and look at these areas.

data/lib/axn/core/context/facade.rb

@@ -43,11 +43,7 @@ module Axn
         end
       end
 
-      def _model_fields
-        action.internal_field_configs.each_with_object({}) do |config, hash|
-          hash[config.field] = config.validations[:model] if config.validations.key?(:model)
-        end
-      end
+      def _model_fields = action.class._model_fields
 
       def action_name = @action.class.name.presence || "The action"
 

data/lib/axn/core/contract/validator_class_cache.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Axn
+  module Core
+    module Contract
+      # Per-class cache of the one-off validator classes `Axn::Validation::Fields.validator_class_for`
+      # would otherwise compile fresh on every `.call` for every declared top-level field and subfield
+      # (PRO-3050). Mirrors `Redaction#_contract_redaction` exactly: outer key is `equal?` on the three
+      # copy-on-write config arrays (self-invalidating on any redeclaration, subclass, or
+      # Mountable/Factory rebuild — see redaction.rb's doctrine comment, which this reuses verbatim),
+      # inner key is the `FieldConfig`/`ShapeConfig` object's own IDENTITY.
+      #
+      # Identity, never `validations`: a config's `#validations` is not a stable object across reads.
+      # `Executor#_with_effective_coerce` mints a fresh merged Hash every call when `coerce_input_types`
+      # resolves on, and a config reached only via `internal_field_configs=`/`subfield_configs=` (never
+      # declared) can answer a DIFFERENT Hash on every `#validations` read (stored_shape_traversal_spec's
+      # generative member) — keying on either would never hit, or worse, would grow the table forever.
+      # The config object itself has neither problem: it is a frozen `Data`, minted once and replaced
+      # wholesale on redeclaration, never mutated.
+      #
+      # The SAME config can legitimately need two different compiled classes in one process — the
+      # `coerce_input_types` gate is per-call/per-class/global and can flip between calls — so the inner
+      # table is keyed on [config, coerce] rather than on config alone.
+      module ValidatorClassCache
+        def _validator_class_cache
+          internals = internal_field_configs
+          externals = external_field_configs
+          subfields = subfield_configs
+          memo = @_axn_validator_class_cache
+          return memo if memo&.current?(internals, externals, subfields)
+
+          @_axn_validator_class_cache = ValidatorClassCacheTable.new(internals:, externals:, subfields:)
+        end
+
+        # The compiled validator class for one config under one coerce state, built once per class per
+        # (config, coerce) pair and reused across every `.call`. `effective_validations` is the caller's
+        # already-resolved Hash (with `_with_effective_coerce` applied if relevant) — computed by the
+        # caller regardless of hit/miss, same as before this cache existed, so a hit only saves the
+        # `Class.new` + `validates` compilation, not the coerce merge.
+        def _cached_validator_class_for(config:, effective_validations:, coerce:)
+          _validator_class_cache.fetch(config:, coerce:) do
+            Axn::Validation::Fields.validator_class_for(field: config.field, validations: effective_validations)
+          end
+        end
+      end
+
+      # The table `_validator_class_cache` hands out. Mutable (so not a `Data`), one Hash slot written
+      # once per (config, coerce) pair. `||=` is safe here (unlike `_contract_redaction`'s `dynamic`
+      # flag): a compiled Class is always truthy, so there is no false/nil tri-state to guard.
+      class ValidatorClassCacheTable
+        def initialize(internals:, externals:, subfields:)
+          @internals = internals
+          @externals = externals
+          @subfields = subfields
+          # Per config, by identity — a FieldConfig/ShapeConfig defines no `hash`/`eql?` axn would want
+          # to run (its `validations` Hash may hold a caller-supplied option container that does), and
+          # identity is the right question anyway: the stored config is the one axn built.
+          @classes = {}.compare_by_identity
+        end
+
+        def current?(internals, externals, subfields)
+          @internals.equal?(internals) && @externals.equal?(externals) && @subfields.equal?(subfields)
+        end
+
+        def fetch(config:, coerce:)
+          by_coerce = (@classes[config] ||= {})
+          by_coerce[coerce] ||= yield
+        end
+      end
+    end
+  end
+end

data/lib/axn/core/contract.rb

@@ -7,6 +7,7 @@ require "active_support/core_ext/module/delegation"
 require "active_support/core_ext/object/blank"
 
 require "axn/core/contract/redaction"
+require "axn/core/contract/validator_class_cache"
 require "axn/core/contract/shape_declaration"
 require "axn/core/validation/fields"
 require "axn/core/flow/handlers/invoker"
@@ -365,6 +366,7 @@ module Axn
         # and in the same lookup position as when it lived in this file.
         include ShapeDeclaration
         include Redaction
+        include ValidatorClassCache
 
         # rubocop:disable Metrics/ParameterLists
         def expects(
@@ -534,23 +536,70 @@ module Axn
           end
         end
 
+        DeclaredFieldsCacheEntry = Data.define(:internal_field_configs, :external_field_configs, :fields)
+
+        # `configs.map(&:field)` was a fresh Array on every call — `Redaction#_context_slice` alone
+        # calls this twice per logged line (inbound + outbound), and the context facade calls it twice
+        # per action call. Cached per direction, invalidated by the identity of BOTH config arrays
+        # (rather than only the one a given direction reads) for simplicity: an outbound-only
+        # redeclaration then occasionally invalidates the (unaffected) :inbound slot too, which is
+        # never a wrong answer, only an avoidable rebuild.
+        #
+        # The cached Array is FROZEN before it's stored: `ContextFacade` exposes this exact object
+        # publicly as `Result#declared_fields`, so a fresh Array per call used to confine any caller
+        # mutation to that one facade — reusing the same object across every future call turns that
+        # mutation into permanent cache corruption (a caller-appended field name would start defining
+        # readers/passing `expose` for undeclared output on every subsequent call of the class) unless
+        # the shared object refuses to be mutated at all.
         def _declared_fields(direction)
           raise ArgumentError, "Invalid direction: #{direction}" unless direction.nil? || %i[inbound outbound].include?(direction)
 
+          internals = internal_field_configs
+          externals = external_field_configs
+          cache = (@_axn_declared_fields_cache ||= {})
+          cached = cache[direction]
+          return cached.fields if cached && cached.internal_field_configs.equal?(internals) && cached.external_field_configs.equal?(externals)
+
           configs = case direction
-                    when :inbound then internal_field_configs
-                    when :outbound then external_field_configs
-                    else (internal_field_configs + external_field_configs)
+                    when :inbound then internals
+                    when :outbound then externals
+                    else (internals + externals)
                     end
 
-          configs.map(&:field)
+          cache[direction] = DeclaredFieldsCacheEntry.new(internal_field_configs: internals, external_field_configs: externals,
+                                                          fields: configs.map(&:field).freeze)
+          cache[direction].fields
+        end
+
+        ModelFieldsCacheEntry = Data.define(:internal_field_configs, :value)
+
+        # Field => model options for every internal field carrying `model:`, cached per class: a pure
+        # function of `internal_field_configs`, rebuilt only when that array's identity changes (any
+        # redeclaration, subclass, or Mountable/Factory rebuild — see Redaction's doctrine comment).
+        # Moved here from the context facade instance (was rebuilt from scratch on every reader
+        # definition — O(fields defined × contract size) per action instance, since both the outbound
+        # Result facade and the inbound InternalContext facade instantiate one per call).
+        #
+        # Frozen before caching, same reasoning as `_declared_fields`: this is a public class method
+        # (so any caller can hold the live Hash), and the old per-call rebuild used to confine a
+        # caller mutation to that one read — reusing the same Hash across every future call would
+        # otherwise turn a mutation into permanent cross-call cache corruption.
+        def _model_fields
+          fields = internal_field_configs
+          cached = @_axn_model_fields
+          return cached.value if cached && cached.internal_field_configs.equal?(fields)
+
+          value = fields.each_with_object({}) { |config, hash| hash[config.field] = config.validations[:model] if config.validations.key?(:model) }
+          @_axn_model_fields = ModelFieldsCacheEntry.new(internal_field_configs: fields, value: value.freeze)
+          value
         end
 
         # Everything below is reached only with an implicit receiver, from here and from the other declaration
         # modules extended onto the same class. It is private because an `_`-prefixed name in a module extended
         # onto every action class otherwise lands there as a PUBLIC singleton method, so the convention and the
         # surface disagree. `_declared_fields` stays public above: the context facade, the redaction slice and
-        # `Mountable`'s step passthrough call it on the action class from other files.
+        # `Mountable`'s step passthrough call it on the action class from other files. `_model_fields` stays
+        # public for the same reason: the context facade reads it from `facade.rb`.
         private
 
         # Reject `user_facing:` on any member of an `exposes` shape, at any depth. The block form

data/lib/axn/core/executor.rb

@@ -1053,8 +1053,9 @@ module Axn
         return _validate_inbound! if direction == :inbound
 
         failures = @action_class.send(:external_field_configs).filter_map do |config|
-          errors = Axn::Validation::Fields.collect_errors(field: config.field, validations: config.validations,
-                                                          source: @action.result, action: @action)
+          validator_class = @action_class._cached_validator_class_for(config:, effective_validations: config.validations, coerce: false)
+          errors = Axn::Validation::Fields.errors_for(validator_class, source: @action.result, validations: config.validations, action: @action,
+                                                                       permit_method_call: true)
           ContractFailure.new(config:, path: nil, errors:, stranded_at: nil) if errors.any?
         end
         raise OutboundValidationError, _aggregate_errors(failures, []) if failures.any?
@@ -1132,13 +1133,16 @@ module Axn
         coerce_input_types = _coerce_input_types?
 
         _inbound_configs.filter_map do |config|
-          errors = Axn::Validation::Fields.collect_errors(
-            field: config.field,
-            validations: coerce_input_types ? _with_effective_coerce(config.validations) : config.validations,
+          effective_validations = coerce_input_types ? _with_effective_coerce(config.validations) : config.validations
+          validator_class = @action_class._cached_validator_class_for(config:, effective_validations:, coerce: coerce_input_types)
+          errors = Axn::Validation::Fields.errors_for(
+            validator_class,
             source: config.subfield? ? _resolved_parent_value(config) : @action.internal_context,
+            validations: effective_validations,
             action: @action,
             reader: config.subfield? ? config.reader_as : nil,
             config: config.subfield? ? config : nil,
+            permit_method_call: true,
           )
           next if errors.empty?
 

data/lib/axn/core/validation/fields.rb

@@ -8,7 +8,10 @@ module Axn
     # THE one-off validator collector, for every declared config at every level: a top-level field
     # validates against the context facade (which resolves model records and reads by wire key), a
     # subfield against its canonically-resolved parent value. One (field, validations) pair per
-    # one-off class; raising/settling is the caller's concern (see Executor#_validate_inbound!).
+    # one-off class. The top-level/subfield path (Executor) and ShapeValidator both cache the compiled
+    # class and reuse it across calls/sources — see Contract::ValidatorClassCache and
+    # ShapeValidator#member_validator_classes respectively; raising/settling is the caller's concern
+    # (see Executor#_validate_inbound!).
     class Fields < Base
       def initialize(source)
         super()
@@ -31,7 +34,8 @@ module Axn
           # Two occupants reach here. A top-level/outbound FACADE read: its source is the framework's
           # own context/result facade, whose per-field reader is a safe generated accessor — method
           # dispatch is always permitted (it's not the caller-object dispatch the method_call gate
-          # targets), so the facade call site (collect_errors) passes `permit_method_call: true`. A
+          # targets), so the facade call site (Executor, via .errors_for) passes `permit_method_call:
+          # true`. A
           # SHAPE MEMBER read (ShapeValidator): its source is a caller-supplied element, so it honors
           # the member's own `method_call:` opt-in — the same gate as a subfield (PRO-2907). The
           # permission is carried explicitly by each call site (NOT inferred from @action presence):
@@ -44,18 +48,11 @@ module Axn
         end
       end
 
-      # Returns the ActiveModel::Errors for one (field, validations) pair against a source (empty if
-      # valid). This is THE facade call site (top-level inbound + outbound): its source is the
-      # framework's context/result facade, whose generated reader is safe, so it permits method
-      # dispatch unconditionally. (A subfield reaches read_attribute_for_validation via the reader/
-      # resolve_value branches, never the dispatch-gated else, so the flag is a no-op for it here.)
-      def self.collect_errors(field:, validations:, source:, action: nil, reader: nil, config: nil)
-        errors_for(validator_class_for(field:, validations:), source:, validations:, action:, reader:, config:, permit_method_call: true)
-      end
-
-      # Builds the one-off validator class for a (field, validations) pair. Callers that validate
-      # the same contract repeatedly (e.g. ShapeValidator over array elements) can build this once
-      # and reuse it across sources via .errors_for, avoiding per-call class compilation.
+      # Builds the one-off validator class for a (field, validations) pair. Every caller that validates
+      # the same contract repeatedly builds this ONCE and reuses it across sources via .errors_for:
+      # Contract::ValidatorClassCache for a top-level field/subfield (keyed on the FieldConfig's
+      # identity), ShapeValidator for a shape member (keyed on the member's field name, scoped to one
+      # compiled parent class).
       def self.validator_class_for(field:, validations:)
         Class.new(self) do
           def self.name = "Axn::Validation::Fields::OneOff"
@@ -71,7 +68,7 @@ module Axn
 
       # Runs a validator class against a source and returns its ActiveModel::Errors (empty if valid).
       # `permit_method_call:` governs the dispatch gate in the else branch of
-      # read_attribute_for_validation: the facade call site (collect_errors) passes `true`; a shape
+      # read_attribute_for_validation: the facade call site (Executor) passes `true`; a shape
       # member passes its own `method_call:` opt-in (PRO-2907). It is deliberately independent of
       # `action:` so the two can be threaded separately.
       #

data/lib/axn/internal/call_logger.rb

@@ -48,6 +48,13 @@ module Axn
         return unless level
 
         Axn::Extensions.best_effort(error_context, action: action_class) do
+          # Guarded by the same best_effort boundary as everything else in this block: a custom
+          # logger's severity predicate can itself raise, and that must be absorbed exactly like any
+          # other formatting failure here — some callers (call_async's invocation log, the
+          # enqueue-all completion log) invoke log_at_level with no other best_effort wrapping it, so
+          # checking the predicate outside this boundary could abort the call it only meant to log.
+          next unless would_log?(level)
+
           # Prepare and format context if needed
           context_str = if context_instance && context_direction
                           # Instance-level: use private inputs_for_logging / outputs_for_logging
@@ -91,6 +98,21 @@ module Axn
         defined?(SemanticLogger::Logger) && Axn.config.logger.is_a?(SemanticLogger::Logger)
       end
 
+      # Whether the configured logger would actually emit at `level`, read via the logger's OWN
+      # severity predicate (`debug?`/`info?`/`warn?`/`error?`/`fatal?` — the same query Ruby's stdlib
+      # `Logger` and `SemanticLogger::Logger` already expose). A logger that doesn't respond to the
+      # predicate is assumed to emit, which matches today's behavior exactly — a custom logger
+      # implementing only the plain level methods loses nothing. This is deliberately NOT a switch to
+      # block-form logging (`logger.info { msg }`): that would silently drop the message for a custom
+      # logger whose level methods take a positional argument only and ignore an unused block. Public:
+      # `log_at_level` is the only caller, from this same module, but kept alongside `semantic_logger?`
+      # for the same reason that one is public.
+      def would_log?(level)
+        logger = Axn.config.logger
+        predicate = :"#{level}?"
+        !logger.respond_to?(predicate) || logger.public_send(predicate)
+      end
+
       private
 
       # Labeled readable suffix for the plain line, each group rendered with the same

data/lib/axn/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Axn
-  VERSION = "0.1.0-alpha.5"
+  VERSION = "0.1.0-alpha.5.1"
 end

data/lib/axn.rb

@@ -51,8 +51,15 @@ require "axn/util/execution_context"
 require "axn/mountable"
 require "axn/async"
 
-# Rails integration (if in Rails context)
-require "axn/rails/engine" if defined?(Rails) && Rails.const_defined?(:Engine)
+# Rails integration. The `defined?` check runs once and re-requiring axn is a no-op, so a host that
+# loads axn before Rails -- the conventional RSpec layout does -- would otherwise never get the
+# engine. `:before_configuration` fires from `Rails::Application#initialize`, before railties are
+# collected, and runs immediately if Rails is already past that point.
+if defined?(Rails) && Rails.const_defined?(:Engine)
+  require "axn/rails/engine"
+else
+  ActiveSupport.on_load(:before_configuration) { require "axn/rails/engine" }
+end
 
 module Axn
   def self.included(base)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: axn
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.alpha.5
+  version: 0.1.0.pre.alpha.5.1
 platform: ruby
 authors:
 - Kali Donovan
@@ -82,6 +82,7 @@ files:
 - lib/axn/core/contract/redaction.rb
 - lib/axn/core/contract/shape_declaration.rb
 - lib/axn/core/contract/subfield_contradictions.rb
+- lib/axn/core/contract/validator_class_cache.rb
 - lib/axn/core/contract_for_subfields.rb
 - lib/axn/core/default_call.rb
 - lib/axn/core/executor.rb