julewire-core 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e20df02ec73ceafd282ab52015e46a28f9aa7b1d69461e2622afc301f9e98d40
-  data.tar.gz: 4e12bb12f787534aa5318084f6fa69fc1888590d85874d253c12dbfc6d6701f7
+  metadata.gz: 438690176aa21990767656cfc25cc35ebc89563611eb14f05875c463ef6e54f5
+  data.tar.gz: 6ce7ec058019b2ef04a84ec10f9f5fa22d73014b1449e272b8727fc1cbd9d45a
 SHA512:
-  metadata.gz: 222e5041e3d984b1e3d50a989c461522cf7622257d1698e7e9fdee9f10f2837537a883fbfe16466ac31abf868558807e1a07642e52c894ac020bf71c628a1896
-  data.tar.gz: 75f19494c48c6d46ae6bdf997db3605abc93323180589804d0e6338e1c7e592cd58150fbef9be4ccb5bfba577fb1086745ee8b779b6588aa7996572a55a5563f
+  metadata.gz: b965bae8da19cd50a0acf2df7d2005bb421c4b256fc286c7cfb89d2c58b034eefcdaafded7bfacf02243948f63977e4d390cde723f4f1c3f34f3b646dc9ed96d
+  data.tar.gz: a9623120a2bb1c1af5a5c2c877bfcdc74a71225f6826781348fa479c223dc167ff838fa60b8b0759d829307c1f4a180497746a132b7ab65de94d2f7ceb2f2bb1

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## Unreleased
 
+## 1.0.1 - 2026-06-25
+
+- Harden bounded traversal, ingress copying, and carrier extraction against
+  noisy or hostile record shapes.
+- Keep normalized record constructors strict: symbol-key contracts validate
+  instead of quietly normalizing pipeline-owned data.
+- Default carrier extraction to the byte cap, report extraction status to
+  integrations, reserve truncation metadata keys at field ingress, and keep
+  custom normalization limits out of the thread-local copier pool.
+- Keep output writes independent from flush/close lifecycle locking.
+
 ## 1.0.0 - 2026-06-21
 
 - Initial release: execution-scoped structured logging, propagation, bounded

data/docs/advanced-configuration.md

@@ -13,7 +13,8 @@ is unsupported. Call `Julewire.configure` again.
 User-supplied destination formatter, encoder, output, and processor instances
 are shared by reference. Processors, formatters, and encoders must be stateless
 or otherwise reentrant; core does not synchronize them. Direct outputs are
-wrapped with a per-destination mutex.
+wrapped with a per-destination write mutex; `flush` may overlap writes, while
+terminal `close` is serialized with writes.
 
 When a reconfigure reuses the same output or destination object, core keeps that
 resource open for the new active pipeline and skips teardown through the old

data/docs/context-and-propagation.md

@@ -241,9 +241,9 @@ Julewire::Core::Propagation.restore(envelope, link_executions: true) do
 end
 ```
 
-Restoring an envelope is an explicit trust decision. Core validates shape, and
-outbound injection can enforce a byte limit, but core does not authenticate who
-wrote the carrier. At untrusted boundaries, extract only the carrier fields you
+Restoring an envelope is an explicit trust decision. Core validates shape and
+caps inbound carrier bytes by default, but core does not authenticate who wrote
+the carrier. At untrusted boundaries, extract only the carrier fields you
 intentionally accept, apply any application spoofing/filter policy first, then
 call `Carrier.restore` on that filtered carrier map.
 
@@ -269,7 +269,9 @@ Julewire::Core::Propagation::Carrier.restore(trusted) do
 end
 ```
 
-Use `max_bytes:` when the carrier target has practical size constraints:
+Inbound extraction and restore default to `Carrier::DEFAULT_MAX_BYTES`; pass
+`max_bytes: nil` only for a trusted unbounded carrier. Use `max_bytes:` on
+injection when the carrier target has stricter size constraints:
 
 ```ruby
 headers = Julewire::Core::Propagation::Carrier.inject({}, max_bytes: 8 * 1024)

data/docs/contracts.md

@@ -190,7 +190,8 @@ different Ruby isolation boundary:
 - `Julewire::Core::Execution::ScopeSnapshot` for detached execution scope transfer.
 - Parent-runtime hooks: `emit_envelope`, `emit_summary_record`, and `flush`.
   `emit_envelope` accepts detached input, context, carry, attributes, neutral,
-  scope snapshot, and an `enforce_level:` flag.
+  scope snapshot, `enforce_level:`, and `owned:`. Bridges pass `owned: true`
+  only for envelopes that came from Julewire's own wire format.
 
 Bridge runtimes may expose `emit_without_level` when integration code inside
 the bridge has already applied its own level gate. Parent runtime labels,

data/docs/extensions-and-api.md

@@ -300,11 +300,11 @@ health
 ```
 
 Output lifecycle hooks are sync and local. Runtime timeouts provide one carried
-deadline while core walks destinations, but plain outputs do not receive the
-timeout value and core cannot interrupt blocking raw outputs. After the first
-attempted resource, exhausted deadlines skip later resources. Custom
-destinations own async drain, retry, reopen targets, rotation, and
-timeout-aware shutdown.
+deadline while core walks destinations. Plain outputs receive the timeout only
+when their lifecycle method accepts `timeout:` or `**kwargs`; core still cannot
+interrupt blocking raw output code. After the first attempted resource,
+exhausted deadlines skip later resources. Custom destinations own async drain,
+retry, reopen targets, rotation, and timeout-aware shutdown.
 
 Plain output writes are successful when `write` returns without raising and does
 not return `false`. A plain `false` is treated as a rejected write. A rejection
@@ -363,6 +363,8 @@ an immutable `Record` for formatters and destinations. `Record` is not a raw
 input builder; it is the read-only destination boundary. Use
 `Record.from_normalized_hash` only when an extension already owns a complete
 symbol-key normalized record hash and needs the immutable destination shape.
+That path validates the strict internal contract; it does not clean up
+JSON-style or user-input hashes. Use `RecordDraft.build` at raw boundaries.
 
 ## Public Facade
 
@@ -564,4 +566,5 @@ runtimes fail when called, so application code should not replace it casually.
 
 Core exposes the bridge SPI runtime envelope hook used by bridge code. The hook
 accepts detached input, context, attributes, carry, neutral data, and a scope
-snapshot, then routes them through the active pipeline.
+snapshot, then routes them through the active pipeline. Bridge code may pass
+`owned: true` only for data decoded from Julewire-owned wire formats.

data/docs/internals.md

@@ -97,11 +97,11 @@ own schedulers because worker ractors cannot share the main scheduler object.
 
 ## Remote Envelope Hook
 
-Core keeps `Runtime#emit_envelope(input:, context:, attributes:, carry:, neutral:, scope:, enforce_level:)`
+Core keeps `Runtime#emit_envelope(input:, context:, attributes:, carry:, neutral:, scope:, enforce_level:, owned:)`
 for bridge code. The bridge reconstructs the scope snapshot, and core rebuilds
 a normal record from input, context, attributes, carry, neutral, and that
-snapshot before emitting through the active pipeline. It is not a public
-application API.
+snapshot before emitting through the active pipeline. Bridges pass `owned: true`
+only for Julewire-owned wire data. It is not a public application API.
 
 ## Test Seams
 

data/docs/outputs-and-lifecycle.md

@@ -74,8 +74,11 @@ for `$stdout`, caller-owned loggers, and shared objects.
 
 ## Synchronous Output
 
-Core wraps direct outputs with one mutex. Concurrent emitters do not interleave
-individual encoded records, but a slow sink blocks the emitting thread.
+Core wraps direct output writes with one mutex. Concurrent emitters do not
+interleave individual encoded records, but a slow sink blocks the emitting
+thread. `flush` is lifecycle-only and may overlap writes so slow flushes do not
+stall the emit path; direct outputs should be IO-like or internally safe for
+flush/write overlap. `close` is terminal and serialized with writes.
 
 A synchronous output failure is contained. The destination records output
 failure counters and calls `on_failure`. Core does not retry, back off, or

data/docs/records-and-data-policy.md

@@ -181,8 +181,8 @@ Put redaction in processors or a separate policy gem before formatting.
 
 Truncated containers, containers pruned by `max_depth`, and circular container
 references get `_julewire_truncation` metadata. Serializer keys beginning with
-`_julewire_` are reserved by convention for core metadata; user payloads must
-not use that namespace. Public Julewire record contracts use symbol keys
+`_julewire_` are reserved for core metadata; public field ingress rejects the
+truncation marker as a user key. Public Julewire record contracts use symbol keys
 internally. Payloads should also use one JSON field name per value; mixed key
 types that stringify to the same JSON field are outside the serializer contract.
 Long strings use a `...[Truncated]` suffix. User data that already contains that

data/lib/julewire/core/cli/log_formats/record_decoder.rb

@@ -17,7 +17,7 @@ module Julewire
             def section(value)
               return {} unless value.is_a?(Hash)
 
-              Fields::FieldSet.deep_symbolize_keys(value)
+              Fields::FieldSet.deep_symbolize_owned_keys(value)
             end
 
             def sections(source, sections: Fields::Bags.record_hash_sections)

data/lib/julewire/core/context_store.rb

@@ -72,6 +72,7 @@ module Julewire
         current_field_hash(:neutral)
       end
 
+      # SectionProxy dispatches these dynamically from the public field readers.
       def context_value(key, default:)
         current_field_stack(:context).value_for(key, default: default)
       end
@@ -139,21 +140,25 @@ module Julewire
         end
       end
 
-      def with_propagation(context: {}, carry: {}, execution: {}, link_executions: false, &)
+      def with_propagation(context: {}, carry: {}, execution: {}, link_executions: false, owned: false, &)
         scope = current_scope
-        execution = Fields::FieldSet.deep_symbolize_keys(execution)
+        execution = if owned
+                      Fields::FieldSet.deep_symbolize_owned_keys(execution)
+                    else
+                      Fields::FieldSet.deep_symbolize_keys(execution)
+                    end
         @execution_overlays.push(execution)
         @execution_lineage_overlays.push(link_executions ? Execution::Lineage.from_execution_hash(execution) : nil)
         invalidate_propagation_cache!
 
         begin
           if scope
-            scope.with_carry(carry) do
-              scope.with_context(context, &)
+            scope.with_carry(carry, owned: owned) do
+              scope.with_context(context, owned: owned, &)
             end
           else
-            @ambient_fields.with(:carry, carry) do
-              @ambient_fields.with(:context, context, &)
+            @ambient_fields.with(:carry, carry, owned: owned) do
+              @ambient_fields.with(:context, context, owned: owned, &)
             end
           end
         ensure

data/lib/julewire/core/destinations/destination.rb

@@ -242,9 +242,9 @@ module Julewire
           call_output_lifecycle_safely(method_name, timeout)
         end
 
-        def call_output_lifecycle_safely(method_name, _timeout)
-          # Collection owns the shared deadline; plain outputs expose no timeout API.
-          result = @output.public_send(method_name)
+        def call_output_lifecycle_safely(method_name, timeout)
+          # Sink.wrap centralizes timeout-aware lifecycle dispatch for every output.
+          result = @output.public_send(method_name, timeout: timeout)
           clear_degradation if method_name == :flush && result != false
           result
         rescue StandardError => e

data/lib/julewire/core/destinations/synchronized_output.rb

@@ -4,16 +4,23 @@ module Julewire
   module Core
     module Destinations
       class SynchronizedOutput
+        TIMEOUT_PARAMETER_TYPES = %i[key keyreq].freeze
+        private_constant :TIMEOUT_PARAMETER_TYPES
+
         def initialize(output, close_output: false)
           Sink.validate_writeable!(output)
           @output = output
           @close_output = close_output
           @mutex = Mutex.new
+          @lifecycle_mutex = Mutex.new
+          @lifecycle = lifecycle_methods
         end
 
         def after_fork!
           @mutex = Mutex.new
+          @lifecycle_mutex = Mutex.new
           @output.after_fork! if @output.respond_to?(:after_fork!)
+          @lifecycle = lifecycle_methods
           self
         end
 
@@ -22,27 +29,36 @@ module Julewire
         def resource_identity = @output
 
         def write(value)
-          @mutex.synchronize { @output.write(value) }
+          @mutex.synchronize do
+            return false if output_closed?
+
+            @output.write(value)
+          end
         end
 
-        def flush
-          @mutex.synchronize do
-            return true unless @output.respond_to?(:flush)
+        def flush(timeout: nil)
+          @lifecycle_mutex.synchronize do
+            lifecycle = @lifecycle[:flush]
+            return true unless lifecycle
 
-            @output.flush != false
+            call_lifecycle(:flush, lifecycle, timeout: timeout) != false
           end
         end
 
-        def close
-          @mutex.synchronize do
-            return true if output_closed?
-
-            result = if @close_output && @output.respond_to?(:close)
-                       @output.close
-                     elsif @output.respond_to?(:flush)
-                       @output.flush
-                     end
-            result != false
+        def close(timeout: nil)
+          @lifecycle_mutex.synchronize do
+            # Close is terminal: lifecycle calls stay serialized, and the write mutex
+            # keeps the underlying output from being closed while a write is in flight.
+            @mutex.synchronize do
+              return true if output_closed?
+
+              result = if @close_output && @lifecycle[:close]
+                         call_lifecycle(:close, @lifecycle.fetch(:close), timeout: timeout)
+                       elsif @lifecycle[:flush]
+                         call_lifecycle(:flush, @lifecycle.fetch(:flush), timeout: timeout)
+                       end
+              result != false
+            end
           end
         end
 
@@ -51,6 +67,26 @@ module Julewire
         def output_closed?
           @output.respond_to?(:closed?) ? @output.closed? : false
         end
+
+        def call_lifecycle(name, lifecycle, timeout:)
+          return @output.public_send(name, timeout: timeout) if lifecycle.fetch(:timeout)
+
+          @output.public_send(name)
+        end
+
+        def lifecycle_methods
+          %i[flush close].each_with_object({}) do |name, methods|
+            next unless @output.respond_to?(name)
+
+            method = @output.method(name)
+            methods[name] = { timeout: accepts_timeout_keyword?(method) }.freeze
+          end.freeze
+        end
+
+        def accepts_timeout_keyword?(method)
+          method.parameters.any? { |type, name| TIMEOUT_PARAMETER_TYPES.include?(type) && name == :timeout } ||
+            method.parameters.any? { |type, _name| type == :keyrest }
+        end
       end
     end
   end

data/lib/julewire/core/diagnostics/doctor.rb

@@ -52,25 +52,25 @@ module Julewire
 
         def destination_info(destinations)
           destinations.transform_values do |destination|
-            {
-              counts: destination[:counts],
-              last_failure: destination[:last_failure],
-              last_loss: destination[:last_loss],
-              status: destination[:status]
-            }.compact
+            component_info(destination, include_loss: true)
           end
         end
 
         def integration_info(integrations)
           integrations.transform_values do |integration|
-            {
-              counts: integration[:counts],
-              last_failure: integration[:last_failure],
-              status: integration[:status]
-            }.compact
+            component_info(integration)
           end
         end
 
+        def component_info(component, include_loss: false)
+          {
+            counts: component[:counts],
+            last_failure: component[:last_failure],
+            last_loss: include_loss ? component[:last_loss] : nil,
+            status: component[:status]
+          }.compact
+        end
+
         def warnings(health)
           [].tap do |items|
             items << warning(:runtime_closed, "runtime is closed") if health.fetch(:closed)

data/lib/julewire/core/diagnostics/failure_snapshot.rb

@@ -16,7 +16,9 @@ module Julewire
               integration: metadata[:integration],
               output_class: metadata[:output_class],
               phase: metadata[:phase],
-              record: record_metadata(metadata[:record_metadata])
+              reason: metadata[:reason],
+              record: record_metadata(metadata[:record_metadata]),
+              status: metadata[:status]
             }.compact.freeze
           end
 

data/lib/julewire/core/execution/handle.rb

@@ -33,6 +33,8 @@ module Julewire
         end
 
         def finish(reason: :closed, fields: {}, attributes: {}, error: nil, severity: nil)
+          # Finishing is one-shot: retrying after partial summary mutation can
+          # duplicate completion data, so failures are reported and stop here.
           return false unless mark_finished
 
           add_completion_attributes(reason)

data/lib/julewire/core/execution/lineage.rb

@@ -15,12 +15,12 @@ module Julewire
             clean_hash(execution, RELATIONSHIP_KEYS)
           end
 
-          def clean_owned_execution_hash(execution)
-            clean_hash!(execution, RELATIONSHIP_KEYS)
+          def clean_normalized_lazy_relationship_hash(execution)
+            clean_normalized_hash(execution, LAZY_RELATIONSHIP_KEYS)
           end
 
-          def clean_lazy_relationship_hash(execution)
-            clean_hash(execution, LAZY_RELATIONSHIP_KEYS)
+          def clean_owned_execution_hash(execution)
+            clean_hash!(execution, RELATIONSHIP_KEYS)
           end
 
           def from_execution_hash(execution)
@@ -50,6 +50,11 @@ module Julewire
             clean_hash!(copy, keys)
           end
 
+          def clean_normalized_hash(execution, keys)
+            copy = execution.is_a?(Hash) ? execution.dup : {}
+            clean_hash!(copy, keys)
+          end
+
           def clean_hash!(copy, keys)
             keys.each do |key|
               Fields::Internal.delete_key!(copy, key)
@@ -182,8 +187,7 @@ module Julewire
 
         def frozen_hash_copy(value)
           value.each_with_object({}) do |(key, field_value), copy|
-            copy[Fields::Internal.normalize_key(key)] =
-              Serialization::ValueCopy.call(field_value, freeze_values: true)
+            copy[key] = Serialization::ValueCopy.call(field_value, freeze_values: true)
           end
         end
       end

data/lib/julewire/core/execution/scope.rb

@@ -109,12 +109,12 @@ module Julewire
           @fields.with(section, fields, owned: owned, &)
         end
 
-        def with_context(fields, &)
-          with_field(:context, fields, &)
+        def with_context(fields = nil, owned: false, **keyword_fields, &)
+          @fields.with(:context, fields, owned: owned, **keyword_fields, &)
         end
 
-        def with_carry(fields, &)
-          with_field(:carry, fields, &)
+        def with_carry(fields = nil, owned: false, **keyword_fields, &)
+          @fields.with(:carry, fields, owned: owned, **keyword_fields, &)
         end
 
         def without_carry(path, &)

data/lib/julewire/core/execution/scope_fields.rb

@@ -55,8 +55,8 @@ module Julewire
           @stacks.delete(section, path)
         end
 
-        def with(section, fields, owned: false, &)
-          @stacks.with(section, fields, owned: owned, &)
+        def with(section, fields = nil, owned: false, **keyword_fields, &)
+          @stacks.with(section, fields, owned: owned, **keyword_fields, &)
         end
 
         def without(section, path, &)

data/lib/julewire/core/facade_methods.rb

@@ -105,7 +105,7 @@ module Julewire
         envelope = Core::Propagation.capture_local
         Fiber.new(**) do |*args|
           with_cleared_configure_guard do
-            Core::Propagation.restore(envelope) { yield(*args) }
+            Core::Propagation.restore(envelope, owned: true) { yield(*args) }
           end
         end
       end
@@ -132,7 +132,7 @@ module Julewire
         envelope = Core::Propagation.capture_local
         Thread.new(*) do |*thread_args|
           with_cleared_configure_guard do
-            Core::Propagation.restore(envelope) { yield(*thread_args) }
+            Core::Propagation.restore(envelope, owned: true) { yield(*thread_args) }
           end
         end
       end

data/lib/julewire/core/fields/field_set.rb

@@ -32,17 +32,19 @@ module Julewire
           end
 
           def deep_dup(value)
-            return {} if value.is_a?(Hash) && value.empty?
-            return [] if value.is_a?(Array) && value.empty?
+            deep_dup_with(value, preserve_truncation_metadata: false)
+          end
 
-            Serialization::ValueCopy.call(value)
+          def deep_dup_owned(value)
+            deep_dup_with(value, preserve_truncation_metadata: true)
           end
 
           def deep_symbolize_keys(value)
-            return {} if value.is_a?(Hash) && value.empty?
-            return [] if value.is_a?(Array) && value.empty?
+            deep_symbolize_keys_with(value, preserve_truncation_metadata: false)
+          end
 
-            Serialization::ValueCopy.call(value, symbolize_keys: true)
+          def deep_symbolize_owned_keys(value)
+            deep_symbolize_keys_with(value, preserve_truncation_metadata: true)
           end
 
           def frozen_copy(value)
@@ -60,6 +62,30 @@ module Julewire
 
           private
 
+          def deep_dup_with(value, preserve_truncation_metadata:)
+            return {} if value.is_a?(Hash) && value.empty?
+            return [] if value.is_a?(Array) && value.empty?
+
+            Serialization::ValueCopy.call(
+              value,
+              preserve_truncation_metadata: preserve_truncation_metadata
+            )
+          end
+
+          def deep_symbolize_keys_with(value, preserve_truncation_metadata:)
+            return {} if value.is_a?(Hash) && value.empty?
+            return [] if value.is_a?(Array) && value.empty?
+
+            Serialization::ValueCopy.call(
+              value,
+              max_array_items: Serialization::Serializer::DEFAULT_MAX_ARRAY_ITEMS,
+              max_hash_keys: Serialization::Serializer::DEFAULT_MAX_HASH_KEYS,
+              max_string_bytes: Serialization::Serializer::DEFAULT_MAX_STRING_BYTES,
+              preserve_truncation_metadata: preserve_truncation_metadata,
+              symbolize_keys: true
+            )
+          end
+
           def coerce_fields!(target, fields, invalid:)
             if fields.is_a?(Hash)
               merge!(target, fields)