julewire-core 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 438690176aa21990767656cfc25cc35ebc89563611eb14f05875c463ef6e54f5
-  data.tar.gz: 6ce7ec058019b2ef04a84ec10f9f5fa22d73014b1449e272b8727fc1cbd9d45a
+  metadata.gz: 8dcf4adb34508c1956a296d585981b88af27d8be7d0e63e9a3fe130b2c835f3b
+  data.tar.gz: 66cf51de3387a96f280c23badc8d847b07c53f069bd1aa5bcc7d15f72bfb4cff
 SHA512:
-  metadata.gz: b965bae8da19cd50a0acf2df7d2005bb421c4b256fc286c7cfb89d2c58b034eefcdaafded7bfacf02243948f63977e4d390cde723f4f1c3f34f3b646dc9ed96d
-  data.tar.gz: a9623120a2bb1c1af5a5c2c877bfcdc74a71225f6826781348fa479c223dc167ff838fa60b8b0759d829307c1f4a180497746a132b7ab65de94d2f7ceb2f2bb1
+  metadata.gz: e5f73d78908ae3a654c69f91eb05aa97d804e5ad9d087bb709044b7b8f0273c0babc5b4094096d9136378e7cc43a2ad850766cb8307e7883747408551be87424
+  data.tar.gz: eef32910880411f8760142726eb4453b938f073124688ff992bbf3d59a0c6f9a3f3d70a95a020946015d970e7694ba551785436d9755b0faf215bf599769b47e

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## Unreleased
 
+## 1.1.0 - 2026-07-20
+
+- Make carrier extraction status public via `Carrier::Extracted` and rename the
+  convenience reader to `extract_envelope`.
+- Enforce recursive Symbol keys for owned records and protocols; reject invalid
+  processor results and malformed propagation sections instead of normalizing
+  or ignoring them.
+- Require canonical lowercase severity Symbols while retaining case-insensitive
+  String and standard-library Logger integer ingress.
+- Harden bounded serialization, `RecordDraft` isolation/finalization, and
+  processor, summary, and lifecycle failure health; remove reusable bounded
+  transforms and the undocumented `freeze_sections` mode.
+- Remove `Julewire::Testing::Contracts` and `Julewire::Testing::Chaos`; the
+  testing API now contains only capture and null-output observation fixtures.
+- Remove the generic deadline-scheduler SPI; main-process integrations now use
+  only the process-owned shared scheduler, leaving Ractor-safe timeout ownership
+  to the Ractor integration.
+
 ## 1.0.1 - 2026-06-25
 
 - Harden bounded traversal, ingress copying, and carrier extraction against

data/docs/configuration.md

@@ -38,6 +38,10 @@ end
 | `on_failure` | Best-effort callback for contained core failures. |
 | `on_drop` | Best-effort callback for operational drops after a record reaches destination/output handling. |
 
+Severity Symbols must use canonical lowercase values. String configuration
+values are case-insensitive, and standard-library Logger severity integers are
+accepted.
+
 Timeout values must be `nil` or non-negative finite numerics.
 `error_backtrace_lines` must be a non-negative integer.
 
@@ -117,10 +121,11 @@ processors. Output-specific shape belongs in destination formatters. Processors
 are the mutation stage.
 
 Processors receive the current `Julewire::RecordDraft`. Mutate the draft
-directly. Return `:drop` to stop delivery or a different `Julewire::RecordDraft` to
-replace the current draft; any other return value is ignored. Processors own
-the draft until the final record boundary, so direct mutation is the normal hot
-path:
+directly and return `nil` to keep it. Return `:drop` to stop delivery or a
+different `Julewire::RecordDraft` to replace the current draft. Unsupported
+non-`nil` return values keep the current draft but increment `processor_invalid`
+and record last-failure metadata. Processors own the draft until the final
+record boundary, so direct mutation is the normal hot path:
 
 ```ruby
 class AddTenantLabel
@@ -155,11 +160,13 @@ Processor exceptions use the registration policy:
 | `on_error` | Behavior |
 | --- | --- |
 | `:fail_closed` | Default. Emit a `julewire.processor_error` replacement record and stop the chain. |
-| `:fail_open` | Record the failure, keep the current draft, and continue with later processors. |
+| `:fail_open` | Record the failure and continue only when the current draft still satisfies the owned record contract. |
 | `:drop` | Record the failure and suppress the record. |
 
-Public emit input remains defensive. The final immutable record boundary
-validates the Julewire record shape before destinations see it.
+Public emit input remains defensive. Core validates the draft after every
+processor, so a malformed mutation is attributed and dropped before a later
+processor or destination sees it. The final immutable record boundary still
+validates the Julewire record shape.
 
 Destination-local processors run after the global processor chain and before
 one destination formats the record. Use them for sink-specific policy such as

data/docs/context-and-propagation.md

@@ -225,9 +225,22 @@ Execution metadata is restored as ordinary execution fields. Use
 `Julewire.with_execution(..., fields: { trace_id: "..." })` for custom
 execution fields at the public API boundary.
 
+Direct `Propagation.restore` treats its envelope as public/unowned input:
+String keys are normalized, but `_julewire_truncation` remains reserved and is
+rejected. `Carrier.restore` is the owned decoded-wire path; it preserves
+Julewire-generated truncation metadata while restoring the carrier envelope.
+Bridge code may also call `Propagation.restore(..., owned: true)` for a local
+Julewire-owned envelope. That strict path requires a recursively Symbol-keyed
+Hash and requires every present propagation section to be a Hash; it does not
+replace malformed owned sections with empty hashes.
+
 Propagation serializes values through the core serializer. That means values
 cross a log-safe boundary, not an object-identity boundary.
 
+Carrier JSON decode is a key-normalization boundary: decoded String keys become
+Symbols before restore. Once restored, context and carry are owned Symbol-key
+data; integrations must not add String-key overlays.
+
 Core does not redact propagation envelopes. Do not put secrets in context or
 carry unless your app or processor policy handles them.
 
@@ -278,6 +291,11 @@ headers = Julewire::Core::Propagation::Carrier.inject({}, max_bytes: 8 * 1024)
 # => nil when the serialized carrier is too large; the carrier key is removed
 ```
 
+Integrations that need failure status should call `Carrier.extract_result` and
+inspect its public `Carrier::Extracted` fields: `status`, `reason`, `error`,
+and `envelope`. Use `Carrier.extract_envelope` for convenience-only restore
+paths.
+
 The default carrier key is `"julewire"`. Carriers are intentionally
 provider-neutral: core stores only the Julewire propagation envelope. External
 header conventions stay outside core.
@@ -343,6 +361,8 @@ counters.
 - current fiber context store
 - the old active pipeline/output lifecycle
 - live runtime post-close drop and callback-failure state
+- registered named runtimes and their pipelines when called through the main
+  `Julewire` facade; a later named lookup creates a fresh runtime
 
 `health[:counts]` is different: it is monotonic for the current runtime object
 and survives `reset!`. Use it for process-lifetime runtime lifecycle scrapes.

data/docs/contracts.md

@@ -60,53 +60,18 @@ general application surface:
 - `Julewire::TailSampling` as a destination wrapper for execution-level tail
   sampling.
 - `Julewire::Testing::CaptureDestination`, `Julewire::Testing::NullOutput`,
-  `Julewire::Testing.capture`, `Julewire::Testing.configure_capture_destination`,
-  `Julewire::Testing::Contracts`, `Julewire::Testing::Chaos`, and
-  `Julewire::Testing::Coverage` as extension test support.
+  `Julewire::Testing.capture`, and
+  `Julewire::Testing.configure_capture_destination` as small extension test
+  fixtures.
 - `RuntimeLocator.current.emit_without_level` for host-process integrations
   that already apply their framework's level gate.
 
 Extensions should consume these contracts rather than reaching into pipeline,
 runtime, storage, or destination internals.
 
-Testing support is shipped for integration authors, but helper names may still
-change when the ecosystem cleanup demands it.
-
-`Julewire::Testing::Contracts` currently ships these shared assertions for
-extension and integration gems:
-
-- `assert_julewire_bounded_transform_spi_contract`
-- `assert_julewire_deadline_scheduler_spi_contract`
-- `assert_julewire_destination_contract`
-- `assert_julewire_execution_boundary_contract`
-- `assert_julewire_failure_containment_contract`
-- `assert_julewire_formatter_contract`
-- `assert_julewire_integration_failure_contract`
-- `assert_julewire_integration_health_contract`
-- `assert_julewire_integration_ivar_state_contract`
-- `assert_julewire_integration_payload_contract`
-- `assert_julewire_integration_spi_contract`
-- `assert_julewire_integration_timestamp_contract`
-- `assert_julewire_integration_value_contract`
-- `assert_julewire_processor_contract`
-- `assert_julewire_propagation_contract`
-- `assert_julewire_record_draft_transform_contract`
-- `assert_julewire_record_shape_contract`
-- `assert_julewire_record_source_contract`
-- `assert_julewire_runtime_integration_contract`
-- `assert_julewire_truncation_marker_spi_contract`
-- `assert_julewire_validation_spi_contract`
-
-`Julewire::Testing::Chaos` currently ships containment helpers for extension
-test suites:
-
-- `assert_contained`
-- `assert_core_runtime_containment`
-- `assert_destination_chaos_contract`
-- `assert_discovered_chaos_contracts`
-- `assert_emitter_chaos_contract`
-- `catalog`
-- `raiser`
+Core does not ship an assertion DSL or exception-corpus runner. Integration
+tests exercise their production formatter, destination, processor, subscriber,
+and framework boundary directly.
 
 ## Integration SPI
 
@@ -118,6 +83,8 @@ but they are not intended as general application API:
   integration health and scoped health wrappers.
 - `Julewire::Core::Integration::Facade` for integration-owned emits,
   execution boundaries, field overlays, and summary enrichment.
+- `Julewire::Core::Integration::Protocol` for recursive, non-normalizing
+  validation of Symbol-keyed integration protocol data.
 - `Julewire::Core::Integration::Values::Read` for hash/object value reads
   including `value`, `hash_value`, `nested_value`, `path_value`,
   `first_value`, and `blank?`.
@@ -133,7 +100,10 @@ but they are not intended as general application API:
   snapshots without exposing core's internal health cells.
 - `Julewire::Core::Destinations::WriteStep` for destination-style integrations
   that reuse core's format, encode, bound, write, and counter sequence while
-  keeping their own lifecycle and failure policy.
+  keeping their own lifecycle and failure policy. It returns `true` only when
+  the output accepted the encoded record; handled drops and transform failures
+  return `false` after recording health/loss metadata through the supplied
+  callbacks.
 - `Julewire::Core::CLI::LogFormats` for provider-owned CLI file-tail decoding
   and transcoding formats.
 - `Julewire::Core::Processing.register` for integration-owned processor kinds,
@@ -148,14 +118,13 @@ but they are not intended as general application API:
 - `Julewire::Core.sentinel(:name)` for readable, frozen identity markers when
   an integration needs a private empty or missing-value sentinel.
 - `Julewire::Core.deep_compact_empty` for core-compatible empty-field pruning.
-- `Julewire::Core::Scheduling::DeadlineScheduler` for integration-local timeout callbacks
-  that need Julewire's fork-reset behavior.
 - `Julewire::Core::Scheduling::SharedScheduler` for process-wide main-ractor
   timeouts shared by integrations that should not own separate scheduler
   threads.
 - `Julewire::Core::Validation` for shared option and limit validation.
-- `Julewire::Core::Serialization::BoundedTransform` for processors and integrations that need
-  core-compatible bounded traversal before core serializes the result.
+- `Julewire::Core::Serialization::BoundedTransform.call` for processors and
+  integrations that need core-compatible bounded traversal before core
+  serializes the result.
 - `Julewire::Core::Diagnostics::CallbackNotifier` and
   `Julewire::Core::Diagnostics::FailureSnapshot` for destination-style
   integrations that need core-compatible callback and health failure shape.
@@ -181,6 +150,8 @@ different Ruby isolation boundary:
 - `Julewire::Core::UNSET`, `Julewire::Core.emit_input`, and
   `Julewire::Core::Records::LazyEmitInput` to mirror facade emit semantics
   across an isolation boundary.
+- `Julewire::Core::Records::BuildInput` to canonicalize public emit fields or
+  validate integration-owned record input before strict bridge serialization.
 - `Julewire::Core::Execution::Boundary` for shared execution boundary behavior.
 - `Julewire::Core::ContextStore.current`,
   `Julewire::Core::Fields::ContextProxy`,
@@ -188,14 +159,17 @@ different Ruby isolation boundary:
   `Julewire::Core::Fields::CarryProxy`, and
   `Julewire::Core::Fields::SummaryProxy` for bridge-local field bags.
 - `Julewire::Core::Execution::ScopeSnapshot` for detached execution scope transfer.
+- `emit_integration(record, enforce_level:)` on bridge runtimes for strict
+  integration-owned emits inside the isolation boundary.
 - Parent-runtime hooks: `emit_envelope`, `emit_summary_record`, and `flush`.
   `emit_envelope` accepts detached input, context, carry, attributes, neutral,
   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,
-processors, destinations, and outputs remain parent-owned.
+Bridge runtimes may expose `emit_without_level` for public bridge-local callers
+that already applied a level gate. Integration code uses `emit_integration` so
+owned data never falls back through public normalization. Parent runtime
+labels, processors, destinations, and outputs remain parent-owned.
 
 ## Internal implementation
 

data/docs/extensions-and-api.md

@@ -29,7 +29,7 @@ Allowed processor returns:
 nil                         # draft was mutated in place or unchanged
 draft                       # explicit draft return
 :drop                       # stop delivery
-anything else               # ignored; current draft continues
+anything else               # current draft continues and health records it
 ```
 
 Mutate the draft for ordinary enrichment:
@@ -46,6 +46,12 @@ primary processor API:
 draft.fetch(:context).fetch(:account)[:id] = "changed"
 ```
 
+Draft data is already normalized. Processors must use Symbol keys for every
+new or replacement hash key; processors are not a String-key normalization
+boundary. Core validates the current draft after every processor. Invalid data
+is attributed to the processor that produced it, reported, and dropped before a
+later processor can observe it.
+
 Use transform helpers when replacing values or sections. They invalidate cached
 records and keep execution lineage when execution identity is unchanged:
 
@@ -54,6 +60,11 @@ draft.transform_field!(:severity) { :warn }
 draft.transform_section!(:payload) { |payload| payload.merge(sampled: true) }
 ```
 
+Transform identifiers are strict Symbols. `transform_field!` accepts only
+known record fields, and `transform_section!` accepts only documented Hash
+sections. These processor-owned helpers do not normalize String identifiers or
+create ad hoc top-level fields.
+
 Use `transform_record!` for whole-record replacement transforms:
 
 ```ruby
@@ -95,6 +106,9 @@ config.processors.use Julewire::Match.new do
 end
 ```
 
+`Match` condition keys are Symbol keys. A condition whose pattern is `nil`
+matches a present field with a nil value; it does not match a missing field.
+
 For deterministic head sampling, use the registered `:sampling` processor:
 
 ```ruby
@@ -115,13 +129,14 @@ The default is `on_error: :fail_closed`: core attempts to emit a minimal
 `julewire.processor_error` record, the original record is not delivered, and
 later processors are not run. Use `on_error: :fail_open` for non-critical
 enrichment processors that should record the failure, keep the current draft,
-and continue. Use `on_error: :drop` when a failing processor should suppress
-the record. `on_error:` is a registry option, not a processor constructor
-keyword.
+and continue, provided the draft still satisfies the owned record contract.
+Fail-open never forwards malformed data. Use `on_error: :drop` when a failing
+processor should suppress the record. `on_error:` is a registry option, not a
+processor constructor keyword.
 
-Non-raising draft corruption is detected at the final immutable
-`Julewire::Record` boundary and contained as an `emit_record` failure
-without per-processor attribution.
+Non-raising draft corruption is detected immediately after the processor and
+reported as `:processor_data` or `:destination_processor_data` before the
+record is dropped.
 
 Processors can inspect execution lineage before the default formatter strips it
 from public output. Promote only the pieces you want to expose:
@@ -162,10 +177,12 @@ Application emit input crosses a few small objects before it becomes a draft:
 | Facade merge | `Core.emit_input` | Combine positional input and keyword fields without normalizing app objects. |
 | Lazy block | `Records::LazyEmitInput` | Keep block-built payloads lazy until the level gate passes and preserve eager severity helpers. |
 | Threshold peek | `Records::RawInput` | Read severity, source, and event from raw input without building a record. |
-| Draft build | `Draft::BuildInput` | Split raw input into normalized top-level fields plus payload. |
+| Draft build | `Records::BuildInput` | Split public input into known top-level fields plus payload, or validate strict owned input. |
 
-This split keeps below-threshold eager input and lazy blocks cheap while the
-final immutable `Record` boundary still validates the full shape.
+This split keeps below-threshold eager input and lazy blocks cheap. Owned
+integration input is validated before processors, each processor result is
+validated before the next processor, and the immutable `Record` boundary keeps
+the destination contract explicit.
 
 ## Formatters
 
@@ -324,7 +341,7 @@ parts with important ownership or boundary rules.
 `EncodingSanitizer.call` repairs strings into valid UTF-8. It is intentionally
 string-only; passing other objects is a type error.
 
-`FieldSet` is the public helper for integration-owned field hashes. Its
+`FieldSet` is the public helper for defensive field hashes. Its
 documented surface is:
 
 - `coerce`
@@ -336,8 +353,11 @@ documented surface is:
 
 `coerce`, `merge`, and `merge!` normalize string keys to symbols and
 defensive-copy values before inserting them, so later caller mutation does not
-mutate core field containers. Use symbol keys after that boundary. `VALUE_KEY`
-is the key used when non-hash field input is wrapped instead of dropped.
+mutate core field containers. They are public-ingress helpers, not repairs for
+integration-owned or cross-gem protocol data. Use `Integration::Protocol` to
+validate owned data and keep Symbol keys after the ingress boundary.
+`VALUE_KEY` is the key used when non-hash field input is wrapped instead of
+dropped.
 
 Other `FieldSet` singleton helpers are core-internal implementation support and
 are not part of the extension contract.
@@ -349,13 +369,17 @@ Encoders and transport boundaries that need pure log-safe data should use
 `Serializer.call` there.
 
 `RecordFieldTransform` walks core's normalized record containers with
-`BoundedTransform`. It owns record-shape policy only; processors supply the
+`BoundedTransform.call`. It owns record-shape policy only; processors supply the
 actual filtering or replacement policy.
 
 `Carrier` serializes propagation envelopes into flat string carriers for
 external boundaries. It is provider-neutral and does not parse or synthesize
 external headers. Use `max_bytes:` to leave a carrier unchanged and return
 `nil` when the serialized envelope is too large for the target boundary.
+Use `Carrier.extract_result` from integrations that need health/status detail.
+It returns a `Carrier::Extracted` value with `status`, `reason`, `error`, and
+`envelope`. Use `Carrier.extract_envelope` only when a best-effort envelope hash
+is enough.
 
 `Julewire::RecordDraft.build` is the raw-input construction path used by core and
 integration code. `Julewire::RecordDraft#to_record` freezes the final normalized data into
@@ -366,6 +390,10 @@ 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.
 
+Summary finalizer failure callbacks receive the contained error plus
+`phase: :summary_finish` or `phase: :summary_emit`, so integration callbacks
+should accept keyword metadata.
+
 ## Public Facade
 
 `contracts.md` owns the public facade inventory. This section covers usage
@@ -376,12 +404,15 @@ Integrations that keep process-local state can register a reset hook with
 component: :component_name) { ... }`. The hook runs after core has refreshed its
 own process-local state and after the active pipeline has forwarded
 `after_fork!` to destinations.
+Both hook names are strict integration identifiers: pass non-empty Symbols.
+String or non-Symbol names raise at registration and are never normalized.
 
 `Julewire.observe_self!(runtime_name = :default, target: :meta)` starts a
 `Julewire::Core::Diagnostics::MetaObserver`. The observer samples one runtime's
 health and emits health-change records into another named runtime. Pass
 `start: false` and call `sample!` manually when deterministic polling is
-preferred.
+preferred. Call `observer.stop!` to cancel scheduled sampling when the
+observer is no longer needed.
 
 Framework and provider adapters may also use the core integration SPI. The
 `Julewire::Core::Integration` namespace is split by concern:
@@ -418,13 +449,25 @@ procs; return a normalized value or raise.
 
 Runtime access:
 
+- `Integration::Protocol.validate_symbol_keys(value)` for recursive validation
+  of integration-owned data before it crosses an internal gem, thread, or
+  Ractor protocol boundary. It returns the same value and raises `TypeError`
+  for every non-Symbol hash key; it never normalizes protocol data. Validation
+  is iterative and continues beyond the later copy/serialization depth bound.
+- `Integration::Protocol.validate_symbol_hash(value)` additionally requires the
+  owned section itself to be a `Hash`. Direct integration SPI rejects malformed
+  sections immediately. Runtime emit boundaries contain, report, and drop that
+  failure instead of emitting a record with silently removed data.
 - `Integration::Facade.with_execution` for framework integrations that
   build fresh execution attributes and want the same execution boundary as
   `Julewire.with_execution` without copying already-owned attribute hashes.
 - `Integration::Facade.emit` for framework/provider integrations that
   emit already-normalized, adapter-owned record hashes. This is not the
   app-facing `Julewire.emit` input path; integrations should pass explicit
-  record keys such as `:event`, `:source`, `:payload`, and `:attributes`.
+  Symbol record keys such as `:event`, `:source`, `:payload`, and
+  `:attributes`. Every nested hash key must also be a Symbol; this API does
+  not normalize String keys. Custom fields belong inside a documented record
+  section; unknown top-level fields are rejected rather than ignored.
 
 Owned field overlays:
 
@@ -433,7 +476,10 @@ Owned field overlays:
   hashes around callback, request, or message processing.
 - `Integration::Facade.add_context`, `add_carry`, `add_attributes`, and
   `add_neutral` for already-normalized, adapter-owned field hashes added to the
-  current execution or ambient context.
+  current execution or ambient context. Every nested hash key must be a Symbol;
+  these owned overlays do not normalize String keys. Non-Hash values are
+  contract errors and are never silently ignored, including when no execution
+  scope is active.
   `add_carry` and `add_neutral` are deliberate symmetry points for integrations
   that need ambient propagation or formatter-coordination fields outside a
   scoped callback.
@@ -461,9 +507,9 @@ methods or indexed access.
 
 Bounded transforms:
 
-- `Julewire::Core::Serialization::BoundedTransform` when a processor or adapter needs a bounded
-  walk with core-compatible depth, array, hash, string, cycle, and truncation
-  behavior.
+- `Julewire::Core::Serialization::BoundedTransform.call` when a processor or
+  adapter needs a bounded walk with core-compatible depth, array, hash, string,
+  cycle, and truncation behavior.
   It can insert `_julewire_truncation` metadata before the final encoder sees
   the payload.
 - `Julewire::Serializer.truncation_metadata` and serializer truncation
@@ -474,67 +520,16 @@ This SPI is documented support for integration gems, but not a compatibility
 freeze. It may change when the ecosystem gets cleaner. `contracts.md` is the
 source of truth for the current tier inventory.
 
-## Extension Contract Tests
-
-Extensions can require `julewire/core/testing` for small test primitives:
-
-- `Julewire::Testing::CaptureDestination`
-- `Julewire::Testing::NullOutput`
-- `Julewire::Testing.configure_capture_destination`
-- `Julewire::Testing::Chaos`
-- `Julewire::Testing::Contracts`
-- `Julewire::Testing::Coverage`
-
-These helpers are shipped support for Julewire extension and integration gems,
-not runtime application API.
-
-`Julewire::Testing::Chaos.assert_contained(test_context) { |error| ... }`
-runs a small `StandardError` corpus through containment checks. Use it for
-extension paths that promise to absorb formatter, processor, destination, or
-subscriber failures.
-`Julewire::Testing::Chaos.assert_core_runtime_containment(test_context)` runs
-the same corpus through core's curated runtime containment surfaces: processors,
-formatters, encoders, outputs, callbacks, and lifecycle hooks.
-`Julewire::Testing::Chaos.assert_destination_chaos_contract(...)` runs the
-same corpus through a destination's formatter, encoder, output or transport,
-and callback containment paths using destination builders supplied by the
-extension test.
-`Julewire::Testing::Chaos.assert_emitter_chaos_contract(...)` runs the same
-corpus through a subscriber/listener-style entrypoint while the extension test
-keeps ownership of framework-shaped failing inputs.
-`Julewire::Testing::Chaos.catalog { ... }` builds a deterministic component
-catalog, and `assert_discovered_chaos_contracts(...)` runs the corpus through
-registered processor, formatter, encoder, destination, subscriber, and listener
-entries. Use it when an extension can describe its containment surfaces without
-reflecting over framework internals.
-`Julewire::Testing::Chaos.raiser(error)` builds a callable that raises the
-supplied error.
-
-`Julewire::Testing::Contracts` contains shared extension assertions.
-`contracts.md` owns the current helper inventory.
-
-Contract helper tiers:
-
-- Component contracts (`processor`, `formatter`, `destination`,
-  `record_draft`, record shape/source) are the documented extension test surface.
-- Runtime, execution, propagation, integration, validation, truncation, bounded
-  transform, and scheduler contracts are integration SPI tests.
-- Chaos helpers are shipped support for containment checks. They are intended
-  for extension/integration test suites, not app runtime code.
-
-The runtime integration helper emits one point record inside an execution,
-adds context, carry, and summary data, flushes, and asserts that destination
-health is visible. Extensions provide their own output decoder and record paths,
-because formatters may move Julewire fields into a different output shape.
-
-`Julewire::Testing::Coverage` is shipped test support for Julewire
-extension gems. It only requires SimpleCov when `Coverage.start!` runs with
-`COVERAGE` set, so runtime users do not load coverage dependencies.
-
-The execution-boundary helper gives integration and propagation extensions the
-same probe data and lets the extension run it through its own unit of work. The
-failure-containment helper verifies that extension failures do not escape
-application calls and that health reports degradation.
+## Extension Tests
+
+Extensions can require `julewire/core/testing` for four small observation
+fixtures: `Julewire::Testing::CaptureDestination`,
+`Julewire::Testing::NullOutput`, `Julewire::Testing.capture`, and
+`Julewire::Testing.configure_capture_destination`.
+
+Core does not ship an assertion DSL or failure-corpus harness. Integration gems
+test their production formatter, destination, processor, subscriber, and
+framework boundary directly.
 
 ## Internal or Advanced
 
@@ -558,7 +553,8 @@ building another internal record.
 
 `Julewire::Core::RuntimeLocator.current=` is an advanced runtime hook for bridge
 code. A bridge runtime must support the child-side facade methods it exposes and
-the parent-side bridge calls it forwards: `emit_envelope`,
+the facade reset hook `reset_facade!`, strict `emit_integration`, plus the
+parent-side bridge calls it forwards: `emit_envelope`,
 `emit_summary_record`, and `flush`. It is deliberately duck-typed; incompatible
 runtimes fail when called, so application code should not replace it casually.
 

data/docs/health-schema.md

@@ -3,6 +3,12 @@
 `Julewire.health` is an in-process operational snapshot. It is useful for
 metrics, smoke checks, and debug pages. It is not a delivery receipt.
 
+Counters and diagnostic references are updated atomically. A health read is
+not a transaction across those independent values: during a concurrent update,
+one snapshot may combine adjacent observations (for example, a new count with
+the preceding failure reference). Counters remain exact, and later reads
+converge on the latest diagnostic state.
+
 ## Stable Fields
 
 These fields are intended for integration dashboards and contract tests:
@@ -59,9 +65,13 @@ reset on reconfigure. Top-level `generation` increments when configuration
 installs a new pipeline.
 `pipeline.counts[:processor_dropped]` counts intentional processor drops such
 as sampling decisions; processor failures are counted separately under
-`pipeline.counts[:processor_error]`.
+`pipeline.counts[:processor_error]`. Unsupported processor return values keep
+the current draft and increment `pipeline.counts[:processor_invalid]`.
+Malformed processor-owned draft data also increments `processor_invalid`; core
+stops the chain and counts the resulting loss under `processor_dropped`.
 Destination-local processors report the same `processor_dropped` and
-`processor_error` counters under that destination's `counts`.
+`processor_error`/`processor_invalid` counters under that destination's
+`counts`.
 
 `status` fields describe current health for the active runtime generation.
 Runtime, pipeline, and destination failure counters plus `last_failure` /

data/docs/internals.md

@@ -11,12 +11,14 @@ The runtime stores immutable snapshots of:
 - pipeline
 - whether the active pipeline has been closed
 
-Writes are serialized where state transitions need serialization. Main-ractor
-hot-path reads use the current frozen runtime state without taking a global
-runtime lock; state transitions swap that reference under the runtime state
-mutex. Health and counters use their own synchronization outside that mutex.
-Non-main ractors use ractor-local runtime storage because they cannot touch the
-main runtime object directly.
+Main-ractor hot-path reads use the current frozen runtime state without taking
+a global runtime lock. State transitions replace that snapshot atomically;
+configure and reset are additionally serialized with the configure mutex while
+close may overlap them. The successful atomic transition owns the previous
+pipeline lifecycle, so concurrent close/reset operations cannot close the same
+pipeline twice. Health and counters use their own synchronization. Non-main
+ractors use ractor-local runtime storage because they cannot touch the main
+runtime object directly.
 
 Configuration, reconfigure, reset, and close are state transitions. They should
 stay boring and explicit.
@@ -67,10 +69,15 @@ extensions do not pay repeated equivalent-key scans.
 
 `Records::RawInput` reads app-facing emit input before record construction.
 `Integration::Values::Read` extracts best-effort values from framework objects.
-`Integration::Values::Shape` normalizes adapter-built hashes. `Fields::FieldSet`
-owns trusted field-bag copying, merging, and key normalization after values have
-entered core. `Fields::Lookup` is for display reads that tolerate symbol/string
-keys and return `nil` for unreadable inputs.
+`Integration::Values::Shape` normalizes adapter-built hashes at framework
+ingress. `Fields::FieldSet` owns public field-bag copying, merging, and key
+normalization at application or framework ingress. Once data is owned,
+`Integration::Protocol` and strict deep validation require recursively Symbol-
+keyed hashes; cross-gem code does not repair String keys. `Fields::Lookup` is
+for best-effort display reads with the exact requested key and returns `nil` for
+unreadable inputs; it does not bridge Symbol/String key forms inside normalized
+records. Presentation code that reads decoded wire payloads uses its separate
+`wire_value` helper at that restore boundary.
 
 ## Context Storage
 
@@ -90,10 +97,10 @@ custom destination objects.
 
 ## Scheduling
 
-`Scheduling::DeadlineScheduler` is the small stdlib timer heap. Main-process
-diagnostics and framework integrations use `Scheduling::SharedScheduler` so
-they do not each keep a background timer thread. Ractor integrations keep their
-own schedulers because worker ractors cannot share the main scheduler object.
+Main-process diagnostics and framework integrations use the process-owned
+`Scheduling::SharedScheduler` so they do not each keep a background timer
+thread. Ractor integrations own their stdlib timeout threads because a worker
+Ractor cannot access the main scheduler's concurrent-ruby objects.
 
 ## Remote Envelope Hook
 
@@ -103,12 +110,6 @@ a normal record from input, context, attributes, carry, neutral, and that
 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
-
-Some private methods are intentionally reachable through `Julewire::Testing`.
-They reset process-global registries or storage that normal applications should
-not touch directly.
-
 ## Emit Entrypoints
 
 | Entrypoint | Caller | Level gate | Input ownership |