julewire-core 1.0.0

data/lib/julewire/core/testing/chaos/destination.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Chaos
+        module Destination
+          class << self
+            def assert_contract(test_context, record:, formatter:, encoder:, output:, callbacks:, errors:)
+              {
+                formatter: formatter,
+                encoder: encoder,
+                output: output,
+                callbacks: callbacks
+              }.compact.each do |scenario, builder|
+                assert_scenario(test_context, scenario, builder, record, errors)
+              end
+              nil
+            end
+
+            private
+
+            def assert_scenario(test_context, scenario, builder, record, errors)
+              errors.each do |error|
+                assert_error_contained(test_context, scenario, builder, record, error)
+              end
+              nil
+            end
+
+            def assert_error_contained(test_context, scenario, builder, record, error)
+              Chaos.assert_contained(
+                test_context,
+                errors: [error],
+                description: "destination #{scenario}"
+              ) do |build_error|
+                destination = builder.call(build_error)
+                destination.emit(record)
+              ensure
+                close_destination(destination)
+              end
+            end
+
+            def close_destination(destination)
+              return unless destination.respond_to?(:close)
+
+              destination.close(timeout: 0)
+            rescue StandardError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/chaos/emitter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Chaos
+        module Emitter
+          class << self
+            def assert_contract(test_context, component:, build:, exercise:, errors:)
+              Chaos.assert_contained(test_context, errors: errors, description: component) do |error|
+                emitter = build.call(error)
+                exercise.call(emitter, error)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/chaos/raising_output.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Chaos
+        class RaisingOutput
+          def initialize(error, failures:)
+            @error = error
+            @failures = failures
+          end
+
+          def write(value)
+            raise @error if @failures.include?(:write)
+
+            value.bytesize
+          end
+
+          def flush
+            raise @error if @failures.include?(:flush)
+
+            self
+          end
+
+          def close
+            raise @error if @failures.include?(:close)
+
+            self
+          end
+
+          def after_fork!
+            raise @error if @failures.include?(:after_fork)
+
+            self
+          end
+        end
+
+        private_constant :RaisingOutput
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/chaos.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      # @api extension
+      module Chaos
+        DEFAULT_ERRORS = [
+          RuntimeError.new("julewire chaos runtime"),
+          ArgumentError.new("julewire chaos argument"),
+          TypeError.new("julewire chaos type")
+        ].freeze
+        class << self
+          def assert_contained(test_context, errors: DEFAULT_ERRORS, description: nil)
+            raise ArgumentError, "block required" unless block_given?
+
+            errors.each do |error|
+              yield error
+            rescue StandardError => e
+              test_context.flunk(containment_message(description, error, e))
+            end
+            nil
+          end
+
+          def assert_core_runtime_containment(test_context, runtime: Julewire, reset: nil, errors: DEFAULT_ERRORS)
+            reset ||= -> { runtime.reset! }
+            raise ArgumentError, "reset must respond to call" unless reset.respond_to?(:call)
+
+            CoreRuntime.assert_contract(test_context, runtime: runtime, reset: reset, errors: errors)
+          end
+
+          def catalog(&)
+            Catalog.build(&)
+          end
+
+          def assert_discovered_chaos_contracts(test_context, catalog:, errors: DEFAULT_ERRORS)
+            Catalog.assert_contract(test_context, catalog: catalog, errors: errors)
+          end
+
+          def assert_destination_chaos_contract(test_context, record:, formatter:, encoder:, output:,
+                                                callbacks: nil, errors: DEFAULT_ERRORS)
+            Destination.assert_contract(
+              test_context,
+              record: record,
+              formatter: formatter,
+              encoder: encoder,
+              output: output,
+              callbacks: callbacks,
+              errors: errors
+            )
+          end
+
+          def assert_emitter_chaos_contract(test_context, component:, build:, exercise:, errors: DEFAULT_ERRORS)
+            Emitter.assert_contract(
+              test_context,
+              component: component,
+              build: build,
+              exercise: exercise,
+              errors: errors
+            )
+          end
+
+          def raiser(error = RuntimeError.new("julewire chaos"))
+            ->(*) { raise error }
+          end
+
+          private
+
+          def containment_message(description, expected_error, leaked_error)
+            unless description
+              return "expected #{expected_error.class} to be contained, leaked #{leaked_error.class}: #{leaked_error}"
+            end
+
+            "expected #{description} chaos to be contained, leaked #{leaked_error.class}: #{leaked_error}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/contracts/component.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Julewire
+  module Core
+    module Testing
+      module Contracts
+        module Component
+          def assert_julewire_processor_contract(processor, draft: build_julewire_contract_draft)
+            assert_respond_to processor, :call
+
+            result = processor.call(draft)
+            return :drop if result == :drop
+
+            result = draft unless result.is_a?(Julewire::Core::Records::Draft)
+            result.to_record
+            result
+          end
+
+          def assert_julewire_formatter_contract(formatter, record: build_julewire_contract_record)
+            assert_respond_to formatter, :call
+
+            formatted = formatter.call(record)
+            encoded = Julewire::Core::Serialization::JsonEncoder.new.call(formatted)
+
+            assert_kind_of String, encoded
+            formatted
+          end
+
+          def assert_julewire_destination_contract(destination, record: build_julewire_contract_record)
+            %i[name emit flush close health].each do |method_name|
+              assert_respond_to destination, method_name
+            end
+
+            assert_nil destination.emit(record)
+            assert destination.flush(timeout: 0)
+            assert destination.close(timeout: 0)
+            assert_kind_of Hash, destination.health
+            destination
+          end
+
+          def assert_julewire_record_shape_contract(record: build_julewire_shape_contract_record)
+            Julewire::Core::Records::Record.validate_normalized!(record)
+
+            data = record.to_h
+            assert_julewire_record_data_shape!(record, data)
+            assert_julewire_record_formatter_shape!(record)
+            assert_julewire_record_serializer_shape!(record)
+
+            record
+          end
+
+          def build_julewire_contract_record(fields = {})
+            build_julewire_contract_draft(fields).to_record
+          end
+
+          def build_julewire_contract_draft(fields = {})
+            Julewire::Core::Records::Draft.build(
+              {
+                severity: :info,
+                kind: :point,
+                event: "test.event",
+                source: "test",
+                message: "test message",
+                attributes: { "test.attribute" => "value" },
+                payload: { value: 1 }
+              }.merge(fields),
+              context: {},
+              scope: nil,
+              freeze_sections: false
+            )
+          end
+
+          private
+
+          def assert_julewire_record_data_shape!(record, data)
+            assert_julewire_symbol_keys!(data)
+            assert_equal(
+              Julewire::Core::Records::Record::REQUIRED_KEYS,
+              data.keys & Julewire::Core::Records::Record::REQUIRED_KEYS
+            )
+            assert record.frozen?
+            assert record.serializable_data.frozen?
+            refute data.fetch(:execution).key?(:ancestors)
+            refute data.fetch(:execution).key?(:ancestors_truncated)
+            assert_equal [{ type: :request, id: "root-1" }], record.lineage.ancestors
+            assert_equal "root-1", record.lineage.root_reference[:id]
+          end
+
+          def assert_julewire_record_formatter_shape!(record)
+            formatted = Julewire::Core::Serialization::Serializer.call(
+              Julewire::Core::Records::Formatter.new.call(record),
+              compact_empty: true
+            )
+            refute formatted.key?("carry")
+            assert_equal "visible", formatted.dig("execution", "custom")
+            %w[root parent ancestors depth ancestors_truncated].each do |key|
+              refute formatted.fetch("execution").key?(key)
+            end
+          end
+
+          def assert_julewire_record_serializer_shape!(record)
+            serialized = Julewire::Core::Serialization::Serializer.call(record)
+            assert_equal(
+              Julewire::Core::Serialization::ValueCopy::CIRCULAR_REFERENCE,
+              serialized.dig("payload", "cycle", "self")
+            )
+            assert_equal Julewire::Core::Serialization::Serializer::NAN_VALUE, serialized.dig("payload", "nan")
+            assert_equal "1.25", serialized.dig("payload", "decimal")
+            JSON.generate(serialized, allow_nan: false)
+          end
+
+          def build_julewire_shape_contract_record
+            cycle = {}
+            cycle[:self] = cycle
+
+            build_julewire_contract_record(
+              execution: {
+                type: :request,
+                id: "execution-1",
+                root: { type: :request, id: "root-1" },
+                parent: { type: :job, id: "parent-1" },
+                ancestors: [{ type: :request, id: "root-1" }],
+                ancestors_truncated: false,
+                depth: 2,
+                custom: "visible"
+              },
+              context: { request_id: "request-1" },
+              neutral: Fields::AttributeKeys.fields("http.request.method" => "GET"),
+              carry: { http: { request_headers: { traceparent: contract_traceparent } } },
+              payload: {
+                value: 1,
+                nested: { string_key: true },
+                cycle: cycle,
+                nan: Float::NAN,
+                decimal: contract_decimal
+              }
+            )
+          end
+
+          def contract_decimal
+            defined?(BigDecimal) ? BigDecimal("1.25") : "1.25"
+          end
+
+          def assert_julewire_symbol_keys!(value)
+            case value
+            when Hash
+              assert(
+                value.keys.all?(Symbol),
+                "expected only symbol keys in #{value.inspect}"
+              )
+              value.each_value { assert_julewire_symbol_keys!(it) }
+            when Array
+              value.each { assert_julewire_symbol_keys!(it) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/contracts/deadline_scheduler.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Julewire
+  module Core
+    module Testing
+      module Contracts
+        module DeadlineScheduler
+          def assert_julewire_deadline_scheduler_spi_contract
+            scheduler = Julewire::Core::Scheduling::DeadlineScheduler.new(thread_name: "julewire-contract-deadline")
+            called = false
+
+            result = scheduler.schedule(0) { called = true }
+
+            assert called
+            assert_nil result
+            assert_nil scheduler.cancel(nil)
+            assert_scheduler_runs_callbacks(scheduler)
+            assert_scheduler_cancel_suppresses_callback(scheduler)
+            assert_scheduler_after_fork_resets_pending_callbacks(scheduler)
+          end
+
+          private
+
+          def assert_scheduler_runs_callbacks(scheduler)
+            queue = Queue.new
+
+            scheduler.schedule(0.001) { queue << :done }
+
+            assert_equal :done, Timeout.timeout(1) { queue.pop }
+          end
+
+          def assert_scheduler_cancel_suppresses_callback(scheduler)
+            queue = Queue.new
+            token = scheduler.schedule(0.01) { queue << :cancelled }
+
+            scheduler.cancel(token)
+            scheduler.schedule(0.02) { queue << :sentinel }
+
+            assert_equal :sentinel, Timeout.timeout(1) { queue.pop }
+            assert_empty Julewire::Core::Testing.nonblocking_queue_values(queue)
+          end
+
+          def assert_scheduler_after_fork_resets_pending_callbacks(scheduler)
+            queue = Queue.new
+
+            scheduler.schedule(0.01) { queue << :old }
+            assert_same scheduler, scheduler.after_fork!
+            scheduler.schedule(0.001) { queue << :new }
+
+            assert_equal :new, Timeout.timeout(1) { queue.pop }
+            assert_empty Julewire::Core::Testing.nonblocking_queue_values(queue)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/contracts/integration.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require_relative "integration_fields"
+
+module Julewire
+  module Core
+    module Testing
+      module Contracts
+        module Integration
+          include IntegrationFields
+
+          def assert_julewire_integration_spi_contract
+            assert_julewire_integration_health_contract
+            assert_julewire_integration_field_overlay_contract
+            assert_julewire_integration_timestamp_contract
+            assert_julewire_integration_payload_contract
+            assert_julewire_integration_value_contract
+            assert_julewire_deadline_scheduler_spi_contract
+            assert_julewire_integration_ivar_state_contract
+          end
+
+          def assert_julewire_validation_spi_contract
+            validation = Julewire::Core::Validation
+            assert_nil validation.validate_options!({ known: true }, %i[known], name: :contract)
+            assert_equal 1, validation.validate_byte_limit!(1, name: :limit)
+            assert_equal 0, validation.validate_integer_limit!(0, name: :count)
+
+            error = assert_raises(ArgumentError) do
+              validation.validate_options!({ unknown: true }, %i[known], name: :contract)
+            end
+            assert_match "unknown contract options: unknown", error.message
+
+            error = assert_raises(ArgumentError) do
+              validation.validate_byte_limit!(0, name: :limit)
+            end
+            assert_match "limit must be nil or a positive Integer", error.message
+
+            error = assert_raises(ArgumentError) do
+              validation.validate_integer_limit!(-1, name: :count)
+            end
+            assert_match "count must be a non-negative Integer", error.message
+          end
+
+          def assert_julewire_truncation_marker_spi_contract
+            assert_equal "[MaxDepth]", Julewire::Core::Serialization::Serializer::MAX_DEPTH_VALUE
+            assert_equal "...[Truncated]", Julewire::Core::Serialization::Serializer::TRUNCATED_SUFFIX
+            assert_equal "_julewire_truncation", Julewire::Core::Serialization::Serializer::TRUNCATION_METADATA_KEY
+            assert_equal(
+              {
+                "truncated" => true,
+                "truncated_fields" => ["array_items"],
+                "limits" => {
+                  "max_array_items" => 1,
+                  "max_depth" => 8,
+                  "max_hash_keys" => 1_000,
+                  "max_string_bytes" => 3
+                }
+              },
+              Julewire::Core::Serialization::Serializer.truncation_metadata(
+                ["array_items"],
+                max_array_items: 1,
+                max_string_bytes: 3
+              )
+            )
+          end
+
+          def assert_julewire_bounded_transform_spi_contract
+            marker_key = Julewire::Core::Serialization::Serializer::TRUNCATION_METADATA_KEY.to_sym
+            result = Julewire::Core::Serialization::BoundedTransform.call(
+              { secret: "value", list: [1, 2], long: "abcdef" },
+              max_array_items: 1,
+              max_string_bytes: 3
+            ) do |_value, key:, **|
+              key == :secret ? "[FILTERED]" : Julewire::Core::Serialization::BoundedTransform::CONTINUE
+            end
+
+            assert_equal "[FI...[Truncated]", result.fetch(:secret)
+            assert_equal "abc...[Truncated]", result.fetch(:long)
+            assert_equal ["array_items"], result.dig(:list, 1, marker_key, "truncated_fields")
+          end
+
+          def assert_julewire_integration_failure_contract(integration:, component:, exercise:)
+            assert_nil exercise.call
+
+            health = Julewire.health
+            integration_health = health.dig(:process_integrations, integration.to_sym)
+
+            assert_equal :degraded, health.fetch(:status)
+            assert_kind_of Hash, integration_health
+            assert_equal :degraded, integration_health.fetch(:status)
+            assert_equal 1, integration_health.dig(:counts, :failures)
+            assert_equal component.to_sym, integration_health.dig(:last_failure, :component)
+            refute_includes integration_health.fetch(:last_failure), :message
+
+            [health, integration_health]
+          end
+
+          def assert_julewire_integration_health_contract
+            Julewire::Core::Diagnostics::ProcessIntegrationHealth.reset!
+            Julewire::Core::Integration::Health.record_failure(
+              :contract,
+              RuntimeError.new("secret"),
+              component: :subscriber
+            )
+
+            degraded = Julewire::Core::Diagnostics::ProcessIntegrationHealth.health.fetch(:contract)
+            assert_equal :degraded, degraded.fetch(:status)
+            assert_equal 1, degraded.dig(:counts, :failures)
+            refute_includes degraded.fetch(:last_failure), :message
+
+            Julewire::Core::Integration::Health.record_success(:contract)
+            recovered = Julewire::Core::Diagnostics::ProcessIntegrationHealth.health.fetch(:contract)
+            assert_equal :ok, recovered.fetch(:status)
+            assert_equal 1, recovered.dig(:counts, :failures)
+            assert_equal "RuntimeError", recovered.dig(:last_failure, :class)
+          ensure
+            Julewire::Core::Diagnostics::ProcessIntegrationHealth.reset!
+          end
+
+          def assert_julewire_integration_timestamp_contract
+            now = Time.utc(2026, 5, 30, 12, 0, 0, 123_456)
+            values = Julewire::Core::Integration::Values::Shape
+
+            assert_equal "2026-05-30T12:00:00.123456000Z", values.timestamp(now)
+            assert_equal "1970-01-01T00:00:01.000000002Z", values.timestamp(1_000_000_002)
+          end
+
+          def assert_julewire_integration_payload_contract
+            values = Julewire::Core::Integration::Values::Shape
+
+            assert_equal({ account_id: "acct-1" }, values.payload_hash("account_id" => "acct-1"))
+            assert_equal(
+              { Julewire::Core::Fields::FieldSet::VALUE_KEY => "raw" },
+              values.payload_hash("raw")
+            )
+            assert_equal({ request_id: "req-1" }, values.hash_or_empty("request_id" => "req-1"))
+            assert_equal({}, values.hash_or_empty("raw"))
+          end
+
+          def assert_julewire_integration_value_contract
+            values = Julewire::Core::Integration::Values::Read
+
+            assert_equal [true, false], [values.blank?(""), values.blank?("value")]
+            assert_equal "symbol", values.value({ key: "symbol" }, :key)
+            assert_equal "string", values.value({ "key" => "string" }, :key)
+            assert_equal "method", values.value(Class.new { def key = "method" }.new, :key)
+            assert_equal(
+              "nested",
+              values.nested_value({ outer: { "inner" => "nested" } }, :outer, :inner)
+            )
+            assert_equal "path", values.path_value({ outer: { "inner" => "path" } }, %i[outer inner])
+            assert_equal :fallback, values.value(Object.new, :missing, default: :fallback)
+          end
+
+          def assert_julewire_integration_ivar_state_contract
+            owner = Object.new
+            state = Julewire::Core::Integration::IvarState.new(:@julewire_contract_install)
+            assert_nil state.fetch(owner)
+            assert_equal :installed, state.store(owner, :installed)
+            assert_equal :installed, state.fetch(owner)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/contracts/integration_fields.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Contracts
+        module IntegrationFields
+          private
+
+          def assert_julewire_integration_field_overlay_contract
+            records = Julewire::Core::Testing.capture(snapshot: true) do
+              Julewire.with_execution(type: :contract, emit_summary: false) do
+                Julewire::Core::Integration::Facade.add_context(contract_context: "ctx")
+                Julewire::Core::Integration::Facade.add_carry(contract_carry: "carry")
+                Julewire::Core::Integration::Facade.add_attributes(contract_attribute: "attr")
+                Julewire::Core::Integration::Facade.add_neutral("contract.neutral": "neutral")
+                Julewire.emit(event: "contract.spi", source: "contract")
+              end
+              Julewire.flush
+            end
+
+            record = records.find { it[:event] == "contract.spi" }
+            flunk("expected integration field overlay contract record") unless record
+
+            assert_equal "ctx", record.dig(:context, :contract_context)
+            assert_equal "carry", record.dig(:carry, :contract_carry)
+            assert_equal "attr", record.dig(:attributes, :contract_attribute)
+            assert_equal "neutral", record.dig(:neutral, :"contract.neutral")
+          ensure
+            Julewire.reset!
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/contracts/record_draft.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Contracts
+        module RecordDraft
+          def assert_julewire_record_draft_transform_contract(draft: build_julewire_transform_contract_draft)
+            draft.transform_field!(:message) { |message| "#{message} transformed" }
+            draft.transform_section!(:payload) { it.merge(section_transformed: true) }
+            draft.transform_record! do |data|
+              data.merge(labels: data.fetch(:labels).merge(record_transformed: "yes"))
+            end
+
+            record = draft.to_record
+            assert_equal "test message transformed", record.fetch(:message)
+            assert record.dig(:payload, :section_transformed)
+            assert_equal "yes", record.dig(:labels, :record_transformed)
+            assert_equal [{ type: "request", id: "root-1" }], record.lineage.ancestors
+            draft
+          end
+
+          def build_julewire_transform_contract_draft
+            build_julewire_contract_draft(
+              execution: {
+                type: "job",
+                id: "job-1",
+                ancestors: [{ type: "request", id: "root-1" }]
+              },
+              labels: { service: "contract" }
+            )
+          end
+        end
+      end
+    end
+  end
+end