phronomy 0.26.0 → 0.27.0

data/docs/decisions/036-context-contract-ownership.md

@@ -0,0 +1,86 @@
+# ADR-036: Context Contract Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch as C1.
+
+This decision clarifies the ownership of existing Context contracts. The
+Journal/Manifest authority model in ADR-012 and the Knowledge model in ADR-013
+remain in force. It does not change either model or introduce a new public API.
+
+## Context
+
+`ContextPolicies::Default` depends on `ContextPolicy` and `ContextPolicyInput`.
+Agent execution also consumes these contracts and selects a concrete policy.
+Keeping the contracts beside execution classes directly under `agent/` makes
+the policy directory appear to depend back on Agent execution.
+
+The shared vocabulary is broader than a policy base class. Policy inputs refer
+to the previous `LLMInputManifest`; plans and generated items have common
+validation rules; `before_llm_input` hooks exchange typed input and result
+values. Moving only a base class would leave those shared contracts split
+across responsibility groups.
+
+The Manifest constructs, validates, and converts record values. It does not
+open transactions or write records to a backend. Its representation therefore
+belongs with the Context contracts used by both producers and consumers.
+
+## Decision
+
+1. Move these seven unchanged files into `lib/phronomy/agent/context_contract/`:
+   - `context_policy.rb`
+   - `context_policy_input.rb`
+   - `context_plan.rb`
+   - `context_plan_validator.rb`
+   - `llm_input_manifest.rb`
+   - `llm_input_build_context.rb`
+   - `llm_input_patch.rb`
+2. Collapse the directory with Zeitwerk, following the existing Engine layout
+   mechanism. Keep the existing `Phronomy::Agent::*` definitions and canonical
+   names, including nested input and Manifest value types. Add no aliases or
+   `Phronomy::Agent::ContextContract` namespace.
+3. Keep `ContextPolicies::Default` with the concrete policy implementations.
+   Keep Context assembly, input building, candidate resolution, Runtime
+   integration, hook invocation, and persistence transactions with their
+   existing execution-side owners.
+4. Preserve policy instance binding, the `call(input)` protocol, hook input and
+   result types, and the Manifest version and encoded representation. Add no
+   descriptor, registry, application registration step, or data migration.
+5. Treat the contracts and concrete policies as separate responsibility groups.
+   They may share a horizontal band in a dependency view. Directory nesting and
+   Ruby namespace nesting do not determine architectural dependency direction.
+
+## Consequences and limits
+
+Policies and hooks reference the contract definitions in their shared group,
+while Agent execution composes and consumes them. The contract files have no
+static dependency on Agent execution or MultiAgent implementation classes.
+Their dependencies on immutable values, token estimation, canonical JSON,
+shared errors, and Storage serialization errors remain unchanged.
+
+The source bodies and mapped file-level dependency graph are preserved. A new
+directory group exposes edges previously internal to `agent/`, so aggregate
+directory edge counts and strongly connected component sizes can increase.
+This is not evidence that the existing file-level cycles were resolved.
+
+The contracts still contain Handoff-related categories and metadata vocabulary.
+That semantic coupling belongs to the subsequent Handoff responsibility review.
+The mixed root directory and execution cycles also require separate work.
+
+Applications continue to `require "phronomy"` and use the same documented
+constants. Individual implementation paths that previously lived directly
+under `agent/` have moved; no forwarding files are retained at those paths.
+
+## Verification obligations
+
+Verify ordinary lazy loading and eager loading, canonical constant names,
+independently accessing each contract, custom Policy binding, Plan validation,
+hook input/result handling, Manifest serialization and restoration, Context
+assembly, and existing migration/persistence integration.
+
+Keep the public API snapshot and RBS unchanged. Match each moved file to its
+source when comparing dependencies. Record the removal of direct policy/hook
+references to the execution directory without presenting aggregate graph
+changes as the elimination of all cycles.
+
+The implementation delivery records its test results separately.

data/docs/decisions/037-common-definition-ownership.md

@@ -0,0 +1,62 @@
+# ADR-037: Common Definition Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch.
+
+The initial extraction scope is amended by
+[038-responsibility-based-source-layout](038-responsibility-based-source-layout.md),
+which adds reviewed general definitions and relocates feature-owned definitions.
+The common-ownership rule and public Error contract below remain in force.
+
+## Context
+
+`lib/phronomy.rb` combines the application loading entry point with shared
+exception definitions and global configuration. Internal consumers of the
+base `Phronomy::Error` therefore refer back to the entry point even though
+they do not explicitly require it.
+
+The shared base exception has no dependency on feature implementations. It
+belongs to a common definition group. An `errors/` group would not convey the
+distinction between general definitions and feature-owned exception contracts.
+The same distinction applies to definitions other than exceptions.
+
+## Decision
+
+1. Use `lib/phronomy/common/` for general definitions shared across the
+   framework that do not belong to a particular feature. These definitions
+   must not depend on concrete Agent, Workflow, Runtime, or other feature
+   implementations. Multiple consumers alone do not establish common ownership.
+2. Move only the base `Phronomy::Error < StandardError` definition from the
+   entry point to `common/error.rb`. Name files after their responsibility;
+   do not introduce an unbounded `common/common.rb` collection.
+3. Collapse `common/` with Zeitwerk to retain `Phronomy::Error` as its canonical
+   name. Do not introduce a second class, alias, or `Phronomy::Common` namespace.
+   Ordinary application loading remains `require "phronomy"`.
+4. Keep existing subclass definitions, inheritance, constructors, and rescue
+   behavior unchanged. Inheriting from `Phronomy::Error` does not require a
+   feature-owned exception to live in `common/`.
+5. Keep the common base independent of entry-point loading. Reading its
+   implementation file in isolation must not initialize the full framework.
+   This is an internal architecture check, not a new public partial-loading API.
+
+## Consequences and limits
+
+Internal references to the shared base resolve to its common definition rather
+than to the loading entry point. The application-facing constant and signatures
+remain unchanged. No new explicit require of the application entry point is
+introduced.
+
+Other exceptions still defined in the entry point, global configuration, and
+the mixed root implementation group need separate ownership reviews. This
+single extraction does not establish that all file or directory cycles have
+been eliminated.
+
+## Verification obligations
+
+Verify isolated base-definition loading, ordinary application loading, and eager
+loading. Check ordinary and preloaded-base initialization orders, canonical
+constant identity, representative subclass hierarchies, and catching a domain
+exception with `rescue Phronomy::Error`. Preserve the public API snapshot and
+RBS signatures. Compare dependency targets against the applied baseline and
+report remaining entry-point references separately.

data/docs/decisions/038-responsibility-based-source-layout.md

@@ -0,0 +1,131 @@
+# ADR-038: Responsibility-Based Source Layout
+
+## Status
+
+Accepted on the architecture refactoring branch; configuration/runtime lifecycle
+ownership amended by
+[039-runtime-configuration-lifecycle-ownership](039-runtime-configuration-lifecycle-ownership.md).
+Concrete-default ownership is subsequently amended by
+[040-configuration-default-composition](040-configuration-default-composition.md).
+Agent default selection and one-shot placement are subsequently refined by
+[044-agent-default-and-one-shot-composition](044-agent-default-and-one-shot-composition.md).
+The Workflow recovery prepend requirement is subsequently replaced by direct
+Runner ownership in
+[054-workflow-terminal-save-single-owner](054-workflow-terminal-save-single-owner.md).
+
+Amends the extraction scope of
+[037-common-definition-ownership](037-common-definition-ownership.md).
+Its common-ownership rule and public Error contract remain unchanged.
+
+## Context
+
+The application loading entry point and the direct `lib/phronomy/` directory
+were distinct sources of mixed ownership. After the base Error extraction,
+the entry point still defined twenty feature/shared exceptions and global
+configuration operations. Thirty-nine direct Ruby files still included
+Workflow implementation, execution contracts, recovery, configuration, and
+general values alongside namespace declarations.
+
+A directory's location must describe its responsibility. A public constant
+under `Phronomy` does not require its implementation file to remain directly
+under `lib/phronomy/`. Conversely, a shared consumer list does not make a
+feature contract a general common definition.
+
+## Decision
+
+1. Reserve `lib/phronomy.rb` for application loading and explicit initialization
+   wiring. Production implementation files under `lib/phronomy/` must not require that entry
+   point. Use Zeitwerk for canonical constant loading and precise requires for
+   dependencies and initialization side effects.
+   The existing `testing/persistence_contract.rb` is a separately documented
+   public entry point for external backend authors. It remains allowed to load
+   Phronomy and RSpec, and remains excluded from production automatic loading.
+   This single named exception does not exempt other files under `testing/`.
+2. Allow only these direct Ruby files under `lib/phronomy/`:
+
+   | File | Reason |
+   |---|---|
+   | `version.rb` | Bundler/gem metadata convention and Zeitwerk GemInflector's version-file convention |
+   | `llm_adapter.rb` | Explicit namespace and extension-SPI documentation |
+   | `tool.rb` | Explicit public Tool authoring namespace and documentation |
+   | `vector_store.rb` | Explicit namespace and backend-SPI documentation |
+   | `output_parser.rb` | Explicit parser namespace declaration |
+   | `testing.rb` | Explicit test-support namespace declaration |
+   | `filter.rb` | Existing Filter convenience loading entry, without feature implementation |
+   | `tracing.rb` | Existing Tracing convenience loading entry, without feature implementation |
+
+   Namespace files must not accumulate method bodies or concrete classes.
+   RubyGems does not mandate this entire allowlist. Keeping these small files
+   is an explicit Phronomy design/compatibility choice. New exceptions to the
+   allowlist require an ownership reason and an amendment to this decision.
+3. Extend `common/` with `CanonicalJSON`, `ConfigurationError`, and
+   `Values::Immutable`. Preserve their canonical names, JSON representation,
+   copy/freeze behavior, and exception hierarchy. The three equivalent private
+   Agent copy helpers delegate to `Values::Immutable.copy`; domain-specific
+   command copying and Workflow copying keep their different contracts.
+4. Move the remaining implementation and exception definitions to their owners:
+
+   | Directory | Responsibility |
+   |---|---|
+   | `engine/` | EventLoop/FSM communication, synchronous callback constraints, execution composition, cancellation/deadlines, runtime diagnostics, invocation and runnable execution contracts |
+   | `recovery/` | Shared recovery vocabulary and execution rehydration requirement; no concrete Agent/Workflow orchestration |
+   | `workflow/execution/` | Workflow DSL, context ownership, runner, and terminal persistence recovery |
+   | `agent/api/` | Agent namespace/event loading and lifecycle extension installation |
+   | `agent/composition/` | One-shot Agent/Persistence composition; method definition loaded by the application entry (ADR-044) |
+   | `agent/lifecycle_contract/` | Agent ownership, handoff, and application stream-delivery exceptions |
+   | `configuration/` | Global configuration values, defaults, accessors, replacement, and scoped overrides |
+   | `runtime_composition/` | Application Runtime/configuration lifecycle coordination and concrete default bindings (ADR-039/040/044) |
+   | `llm_contract/` | Token usage, context-budget failures, and LLM call-boundary failures |
+   | `llm_adapter/ruby_llm_patches.rb` | RubyLLM version-guarded compatibility patch |
+   | `persistence/api/` | Public Persistence facade and repository composition |
+   | `generation/` | GeneratorVerifier pipeline and its confidence failure |
+   | `tool/contract/`, `filter/contract/`, `output_parser/contract/` | Feature-owned shared exceptions |
+
+5. Preserve all existing Ruby constant names, class/module kinds, inheritance,
+   constructors, method visibility, public signatures, and persisted formats.
+   Do not add constant aliases or compatibility files at retired implementation
+   paths. Ordinary application loading remains `require "phronomy"`; arbitrary
+   internal file paths are not a new public partial-loading API.
+6. Use existing Zeitwerk `collapse` and `push_dir(namespace: Phronomy)` facilities.
+   The named nested roots are independent of their enclosing namespace. This
+   retains top-level `Phronomy::WorkflowContext` beside existing nested
+   `Phronomy::Workflow::Persistence` without collapsing the entire Workflow
+   namespace. Load `version.rb` first to establish the non-reloadable Phronomy
+   root namespace. Do not depend on facilities introduced after Zeitwerk 2.6.
+7. Preserve explicit lifecycle initialization. Workflow recovery must be
+   prepended during ordinary application loading. Agent event/recovery
+   extensions must be installed when Agent is loaded. Keep external patching
+   and global namespace reopening files outside automatic name inference.
+   Production eager loading must continue to exclude RSpec conformance support.
+
+## Dependency interpretation and limits
+
+`Event` is an Engine communication contract, not a general-purpose common
+value. The `InvalidAsync*` family belongs to synchronous FSM callback rules:
+Engine and Agent use the entry-action failure as well as Workflow. Moving that
+contract into Workflow implementation would introduce the wrong dependency.
+
+`ExecutionRehydrationRequiredError` belongs to recovery even though its name
+starts with Execution. It is not the timeout/cancellation outcome of fan-out
+composition. `ConfigurationError` is common; `Configuration` is not. Default
+configuration still constructs a concrete LLM adapter and tracer. This change
+groups that existing composition but does not make it implementation-neutral.
+
+Directory relocation does not establish that every remaining dependency is
+downward or that all cycles disappear. Preserve and report actual references.
+An analyzer must resolve namespace operations to their defining implementation
+instead of treating the shortest namespace reopening as the owner of every
+method. Do not mistake a loading entry point for the implementation it loads.
+
+## Verification obligations
+
+- Check the direct-root allowlist and forbid internal entry-point requires.
+- Verify normal and eager loading, independent common/exception loading,
+  preloaded common definitions, nested-namespace access orders, and preserved
+  lifecycle extension installation.
+- Exercise the supported Zeitwerk lower bound and the current locked version.
+- Preserve the API snapshot and RBS without regenerating away a difference.
+- Run existing execution, Workflow, Agent, persistence/recovery, integration,
+  configuration, and serialization tests; run the repository style/type gates.
+- Compare dependencies against the applied baseline with the same analyzer.
+  Mark candidate results as unapplied and identify the exact source tree.

data/docs/decisions/039-runtime-configuration-lifecycle-ownership.md

@@ -0,0 +1,74 @@
+# ADR-039: Runtime and Configuration Lifecycle Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch.
+
+Concrete-default ownership in decision 1 is amended by
+[040-configuration-default-composition](040-configuration-default-composition.md).
+The reset ownership and algorithm below remain current.
+
+Amends the configuration ownership in
+[038-responsibility-based-source-layout](038-responsibility-based-source-layout.md).
+Its loading rules, direct-root allowlist, and compatibility requirements remain
+in force.
+
+## Context
+
+`Phronomy.reset_runtime!` shuts down the default Runtime and replaces global
+configuration only after successful Runtime cleanup. Its configuration grace
+period preservation is application lifecycle coordination between two owners.
+Placing this operation in `configuration/global_configuration.rb` made ordinary
+configuration readers point to a file that also controlled Runtime shutdown.
+
+Engine reads configuration for pool sizes, logging, and shutdown defaults.
+Configuration access must not also own the reverse Runtime lifecycle operation.
+Moving that operation into `common/` would give common definitions an Engine
+dependency. Moving it into an Engine primitive would mix global configuration
+replacement with Runtime execution mechanics.
+
+## Decision
+
+1. Keep configuration values, concrete defaults, global access, replacement,
+   and scoped overrides in `configuration/`.
+2. Place `Phronomy.reset_runtime!` in
+   `runtime_composition/global_runtime.rb`. This responsibility group coordinates
+   Runtime and configuration. Engine and configuration implementation files
+   must not require the composition file or the application entry point.
+3. Keep this namespace-reopening file outside Zeitwerk name inference. Load it
+   explicitly from `lib/phronomy.rb` after global configuration access is
+   available. Do not introduce a `Phronomy::RuntimeComposition` constant,
+   compatibility alias, registration hook, or alternate reset API.
+4. Preserve the reset method body and signature. In particular, Runtime cleanup
+   happens before configuration replacement; an error from cleanup propagates
+   without resetting configuration. Preserve the timeout default, previous
+   grace value handling, laziness of the default Runtime, and return value.
+
+## Dependency interpretation and remaining work
+
+The direct configuration-to-Runtime reference moves to the composition owner.
+Ordinary configuration readers still resolve to the configuration accessor
+file. Reference analysis must resolve each `Phronomy` operation to its actual
+method definition, not assign every operation to an arbitrary namespace file.
+
+This step does not remove the separate cycle formed by concrete defaults:
+`Configuration` constructs `LLMAdapter::RubyLLM`, its base supplies asynchronous
+execution through `Runtime`, and Runtime reads global configuration. The
+default tracer is also concrete. Preserving `Configuration.new` behavior while
+separating default construction requires a separate design decision. Do not
+hide these references with dynamic constant lookup or claim that the entire
+configuration/Engine cycle has disappeared.
+
+## Verification obligations
+
+- Guard that configuration files can be loaded without loading Engine or
+  Runtime composition, exposing the reset operation, or directly referencing
+  Runtime. This loading check does not promise a new public partial-loading API.
+- Verify ordinary application loading exposes the existing reset API and eager
+  loading creates no synthetic composition namespace.
+- Compare production method definitions against the preceding layout candidate;
+  this extraction changes no method bodies.
+- Run the existing configuration, Runtime lifecycle, shutdown participant,
+  compatibility, and integration tests and repository style/type gates.
+- Report remaining cycles with the same analyzer and distinguish the unapplied
+  candidate source tree from the applied baseline commit.

data/docs/decisions/040-configuration-default-composition.md

@@ -0,0 +1,94 @@
+# ADR-040: Configuration Default Composition
+
+## Status
+
+Accepted on the architecture refactoring branch.
+
+Amends concrete-default ownership in
+[038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
+and [039-runtime-configuration-lifecycle-ownership](039-runtime-configuration-lifecycle-ownership.md).
+Their loading, public compatibility, and Runtime reset rules remain in force.
+The provider-call and framework-owned async boundary in
+[027-llm-adapter-provider-boundary](027-llm-adapter-provider-boundary.md) is unchanged.
+
+## Context
+
+`Configuration` holds settings read by Engine and other framework components.
+Its constructor also selected and instantiated `LLMAdapter::RubyLLM` and
+`Tracing::NullTracer`. The adapter base uses Runtime for default asynchronous
+execution, while Runtime reads configuration. Tracing also reads configuration.
+Concrete default selection therefore created reverse implementation references
+from settings to their consumers.
+
+Simply moving the constructor into another file that reopens `Configuration`
+would not separate these responsibilities. Changing `Configuration.new` to
+produce unset components, replacing it with a different application factory,
+or sharing prebuilt defaults would change existing behavior.
+
+## Decision
+
+1. `configuration/` owns setting values, validation, global access, replacement,
+   and scoped overrides. It must not select concrete adapters, tracers, or Runtime
+   implementations. Scalar defaults remain in `Configuration#initialize`.
+2. `runtime_composition/configuration_defaults.rb` selects `RubyLLM` and
+   `NullTracer` with explicit constant references in zero-argument factories.
+   It binds these factories through `Configuration.install_default_factories`
+   during application loading. This method is `@api private`; it is a narrow
+   internal boot operation, not a configurable provider registry or extension SPI.
+3. `Configuration` owns the factory slots it consumes. Binding freezes those
+   slots once. The inherited constructor uses the same binding for subclasses,
+   avoiding class-instance-variable inheritance differences. The constructor
+   invokes each factory for each configuration; it does not cache instances or
+   lazily replace attributes on access. Applications still use `tracer=` and
+   `llm_adapter=` to supply their instances.
+4. `lib/phronomy.rb` explicitly loads the binding file after Zeitwerk setup and
+   before exposing global configuration access or loading lifecycle extensions.
+   The binding file is excluded from automatic namespace inference, as is the
+   existing Runtime coordination file. It introduces no composition namespace.
+   Merely binding factories does not create global configuration, instantiate
+   components, or start Runtime. Arbitrary internal file loading remains outside
+   the public application-loading contract.
+5. Preserve the zero-argument constructor, fresh default instances, subclass
+   behavior, shallow scoped restoration, explicit overrides, Runtime laziness,
+   reset ordering, exception propagation, and previous grace-period handling.
+   No adapter SPI, async method, provider behavior, transport policy, public
+   signature, or persisted format changes in this step.
+
+The binding in decision 2 is limited to default component construction. It does
+not add a Runtime reset registration hook or amend ADR-039's reset algorithm.
+
+## Dependency interpretation and remaining work
+
+This is dependency inversion at the component selection boundary. The settings
+owner defines and consumes factory slots; application composition supplies their
+implementations. Settings can be instantiated with local factories without
+loading Engine, adapters, or tracing. No dynamic constant lookup is used to
+hide implementation references.
+
+The runtime call from `Configuration#initialize` through the factory to a
+concrete constructor still exists. Static reference graphs do not generally
+follow this injected call; reports must distinguish source references from
+runtime factory invocation. Construction does not call `Runtime.instance`:
+the adapter's default pool is acquired later when an async method is called.
+The previous graph cycle was not infinite constructor recursion.
+
+`LLMAdapter::Base` still owns framework async wrappers and references Runtime.
+Runtime, pools, tracing, and Agent retain other dependencies and cycles. This
+step does not claim complete provider independence or an acyclic repository.
+
+## Verification obligations
+
+- Guard that configuration source does not reference Runtime, LLMAdapter, or
+  Tracing, and demonstrate settings construction with supplied local factories
+  without those implementations or application composition loaded.
+- Verify binding and normal/eager loading do not instantiate global settings
+  or start Runtime, including after preloading configuration definitions.
+- Preserve fresh defaults, subclass construction, explicit overrides, scoped
+  component identity restoration, and reset behavior on failed Runtime cleanup.
+- Run the adapter contract/routing tests, configuration and Runtime lifecycle
+  tests, integration tests, and repository style/type/annotation gates.
+- Preserve the API snapshot without regeneration and report the private boot
+  method separately; do not claim that the snapshot covers Configuration or
+  every framework singleton operation.
+- Compare dependencies against the applied baseline with the same analyzer and
+  identify the unapplied candidate's exact source tree.

data/docs/decisions/041-feature-owned-identity-registries.md

@@ -0,0 +1,100 @@
+# ADR-041: Feature-Owned Identity Registries
+
+## Status
+
+Accepted on the architecture refactoring branch.
+
+Amends the implementation owner of the process-local identity registry in
+[025-process-local-agent-ownership-and-runtime-admission](025-process-local-agent-ownership-and-runtime-admission.md).
+The one-owner invariant, Runtime lifetime, public identity operations, durable
+conflict defenses, and EventLoop execution admission remain in force.
+
+## Context
+
+Runtime instantiated Agent and Team identity registries, exposed their specific
+operations, and invoked their shutdown methods directly. Agent identity
+reservation interpreted Agent lifecycle and Storage exceptions inside Engine.
+These are feature policies even though their lifetime is bounded by Runtime.
+
+Moving files while preserving concrete construction, forwarding methods, or
+aliases under Runtime would retain the same dependency. A process-global weak
+map would also lose the required strong ownership and Runtime isolation.
+
+## Decision
+
+1. `Agent::OwnershipRegistry` in `agent/ownership_registry.rb` owns Agent identity
+   reservation, materialization, purge, uncertain-outcome policy, and detachment.
+   `MultiAgent::TeamOwnershipRegistry` in `multi_agent/team_ownership_registry.rb`
+   owns Team identity and construction exclusion. Feature callers use these
+   components directly. The old Runtime registry constants and forwarding
+   methods are removed; they were internal and receive no compatibility aliases.
+2. Each registry lazily registers itself under its class key through Runtime's
+   existing internal shutdown participant contract. Candidate construction has
+   no side effects. Concurrent registration returns one authoritative instance
+   per Runtime. Runtime strongly retains it; neither GC nor execution completion
+   releases an identity. Registration after closure is rejected even for an
+   existing key.
+3. `Runtime#__shutdown_participant(key:)` only looks up an existing participant,
+   including during/after shutdown. It does not create one or admit work.
+   Registry `for(runtime)` reuses it; each registry's gate rejects create/load/
+   purge admission after closure. `existing_for(runtime)` supports `get` without
+   creating a registry. Admitted transitions may finish through the retained
+   instance after closure. Lookup is not an admission bypass.
+4. Participants implement `begin_draining` and `wait_until_idle(deadline)`.
+   Runtime closes every gate under its lifecycle lock, including on EventLoop
+   failure, before waiting outside that lock with one absolute monotonic deadline.
+   Closure must be short, idempotent, and must not call Runtime. For identity
+   registries, idle means no active construction/purge transition, not no live
+   objects. Stable recovery-required entries do not prevent shutdown.
+5. Add the optional `after_runtime_shutdown` operation. Runtime invokes it outside
+   its lifecycle lock only if all participant waits succeed, no participant hook
+   has failed, EventLoop's idle/join checks pass without cancellation timeout,
+   and pools/timers shut down successfully. Existing participants without the
+   hook remain valid. The hook must be idempotent, short, and perform no I/O;
+   its return value is ignored. Agent detachment and Team directory clearing
+   implement this protocol. Runtime does not know their concrete classes.
+6. A finalization exception does not skip later participants. Cleanup is then
+   incomplete, the first failure is retained, and default Runtime replacement
+   is prohibited. Completed releases are not rolled back. Repeated shutdown
+   returns the cached result rather than rerunning partial finalization.
+7. Purge completion/abort/uncertainty updates the Agent object before publishing
+   the corresponding registry state, under the same registry mutex. These
+   internal Agent hooks only update local fields and cannot call Runtime or
+   perform I/O. Shutdown cannot observe a stable transition and detach the
+   Agent before that object's transition has finished.
+
+## Guarantees and limits
+
+| Subject | Property and provider | Failure scope / X0 | Result |
+|---|---|---|---|
+| Mutable Agent identity in one Runtime | At most one live owner per ID, reserved by Agent::OwnershipRegistry before materialization | Normal operation, F0 known failures, and F2 conflicts; X0 not crossed by the registry | YES within this Runtime; no cross-process exclusion |
+| Uncertain Agent create/purge | Existing recovery-required policy retains the reservation | F1 durable outcome uncertainty, possibly with F0; no new X0 guarantee | YES for fail-closed local reservation; NO claim of outcome reconciliation |
+| Old Agent references at Runtime replacement | Registry finalization detaches references before a completed reset | Normal shutdown and F0/F3 stop failures; X0 not managed here | CONDITIONAL on cleanup completion; failed/incomplete cleanup retains the Runtime |
+| Durable facts after Runtime/process loss | Existing Persistence and recovery contracts | F4; X0 remains separate | No new guarantee; confirmed durable state and external effects are not rewritten by this change |
+
+Team's existing conflict, Persistence identity, and construction-failure behavior
+remain unchanged; Agent-specific recovery semantics are not imposed on Team.
+No record format, transaction domain, public API, RBS shape, adapter SPI, or
+worker mechanism changes. Runtime construction/shutdown of an unused instance
+must not cause additional Agent, MultiAgent, or Storage loads; application-entry
+bootstrap is measured separately.
+
+EventLoop still owns Agent execution state/admission and Workflow-specific
+control. Runtime's execution-owner and admission queries remain until a separate
+execution-service extraction. This step does not make Engine feature-neutral.
+Static graphs also do not follow the dynamic participant callbacks: the feature
+implementation still runs through Engine's generic shutdown contract.
+
+## Verification obligations
+
+- Concurrent registration/materialization, exact-instance get/load, duplicate
+  create rejection, incompatible class/Persistence checks, and purge behavior.
+- Lookup without registration, closed admission on shutdown and EventLoop
+  failure, admitted construction completion, and incomplete-cleanup retention.
+- Finalization after quiescence, outside the lifecycle lock, with all later
+  participants visited after an exception and no reset after failure.
+- Purge object/registry transitions cannot be observed as idle halfway through.
+- Source/loading boundaries, API snapshot, RBS, annotations, and existing suites.
+
+Tests of simulated uncertain outcomes verify reservation policy, not arbitrary
+external-effect exactly-once behavior or cross-process ownership.

data/docs/decisions/042-feature-owned-execution-state.md

@@ -0,0 +1,106 @@
+# ADR-042: Feature-Owned Execution State on EventLoop
+
+**Status**: Accepted
+**Date**: 2026-09-21
+**Amends**: [024-event-loop-single-writer-agent-runtime](024-event-loop-single-writer-agent-runtime.md), [025-process-local-agent-ownership-and-runtime-admission](025-process-local-agent-ownership-and-runtime-admission.md), [026-workflow-runtime-admission-and-durable-terminal-barrier](026-workflow-runtime-admission-and-durable-terminal-barrier.md) for implementation ownership, delivery and shutdown admission
+**Complements**: [041-feature-owned-identity-registries](041-feature-owned-identity-registries.md)
+
+## Problem
+
+EventLoop implemented Agent admissions, execution snapshots, completion waiters,
+physical-work tracking and recovery errors, as well as Workflow segment
+admissions, routing and recovery-required state. Its dispatcher selected Agent
+coordinators and Workflow runners. These are feature policies inside Engine;
+retaining them behind dynamic calls would not remove the ownership problem.
+
+## Decision
+
+`Agent::ExecutionRegistry` owns Agent admission, immutable execution entries,
+read-only owner lookup, completion waiters and physical quiescence supervision.
+`WorkflowExecutionRegistry`, under `workflow/execution/`, owns Workflow segment
+admission, instance-to-session routing and recovery-required admissions.
+Both retain the existing semantic identities, exceptions and durable barriers.
+Neither registry is the Runtime-lifetime Agent/Team identity registry of ADR-041.
+
+All normal feature state mutation still runs on the one EventLoop thread.
+Workers only enqueue results or physical-completion notifications. The Engine
+`ExecutionReceiver` base defines an internal registration/delivery/lifecycle
+contract; it is not an application callback or plugin SPI. Feature code creates
+its receiver lazily. Engine never constructs a concrete feature receiver and
+does not interpret feature IDs, commands, admission states or exceptions.
+Runtime provides only a non-creating EventLoop lookup for feature inspection.
+
+### Registration, delivery and drain
+
+One EventLoop strongly retains one receiver per feature key. Registration is
+allowed only while running. Existing lookup never reopens admission or creates
+another loop. A receiver is bound to its original EventLoop.
+
+The generic FIFO delivery contains a registered receiver, immutable command,
+admission flag and optional caller completion. An in-memory envelope token
+identifies only a pending delivery; it is not durable identity, a generation
+counter, or authority for accepting a semantic result. Feature coordinators
+continue to validate execution revisions, operation IDs and current FSM state.
+
+Engine closes new receiver registration and new admission deliveries before
+testing idleness. Agent start/approval resume, Recovery install/resolve and
+Workflow start/resume are new requests at this boundary. A request queued before
+drain remains accepted and may establish its feature admission during drain.
+Existing worker results, physical-completion notifications, cancellation and
+session events may continue while the loop drains. A continuation cannot claim
+a new admission after the gate closes.
+
+Engine counts a queued or currently dispatching receiver message until dispatch
+finishes. This covers the interval before the feature admission exists. Feature
+idleness covers admission-before-FSM-registration and logical-completion-before-
+physical-quiescence intervals. Suspended/recovery-required admissions retain
+their exclusion without indefinitely preventing shutdown.
+
+Feature state reads/writes and Engine idleness use the same lifecycle mutex.
+`idle?` is called with that lock held and must be short, nonblocking, and must
+not call Runtime or reacquire the lock. Other state operations use the shared
+synchronization helper. Delivery, TaskResult callbacks and receiver shutdown
+execute outside the lock. Workflow routing resolves the admission and enqueues
+to the currently admitted FSM under that same lock; it does not use a stale
+lookup followed by an independent enqueue.
+
+Generic FSM registration may attach its receiver. When the FSM reports
+recovery-required retirement, Engine notifies that receiver; Workflow decides
+how to retain its logical admission. Engine does not inspect Workflow state.
+
+### Failure and final invalidation
+
+On dispatcher failure, new delivery is closed. Engine fails current/queued
+request completions and FSM waiters, then notifies every receiver with the
+failure on the failing EventLoop thread. Each receiver clears its own state.
+
+On normal shutdown, Engine notifies receivers only after its thread has joined.
+This is exclusive final reference invalidation, not management-thread execution
+progression. Agent fails retained nonterminal completion waiters with
+`ExecutionRehydrationRequiredError`; Engine never selects that exception.
+Workflow retains the prior behavior of not fabricating a terminal result from
+an uncertain durable outcome. A receiver cleanup exception does not prevent
+later receivers from being visited; cleanup is incomplete and default Runtime
+replacement is refused. A loop still alive at timeout is not invalidated.
+
+## Guarantees and limits
+
+| Subject/property | Provider | Failure/boundary | Result and condition |
+|---|---|---|---|
+| Same-process exclusion and single-writer live state | Feature registries, EventLoop delivery and shared lifecycle lock | F2/F3; no X0 | YES within one Runtime; no cross-process exclusion |
+| Clean shutdown waits for accepted admission and supervised physical work | Engine pending-delivery count plus feature idle predicates and OffloadPool completion | F0/F3; may observe work that crossed X0 | CONDITIONAL on work becoming quiescent before shutdown deadlines; no external effect rollback |
+| Failed/terminated loop cannot continue authoritative live mutation | Closed delivery gate, loop-thread checks and exclusive receiver invalidation | F0/F3/F4; no new X0 | YES for framework-managed live state; process loss requires existing durable recovery |
+| Uncertain durable execution is not released as successful | Existing Agent/Workflow durable barriers and recovery states | F1/F4; X0 unchanged | CONDITIONAL on the existing Persistence/reconciliation contracts; this change adds no durability or exactly-once guarantee |
+
+Public Agent/Workflow APIs, persisted formats, TaskResult semantics and the
+OffloadPool worker implementation are unchanged. Internal EventLoop feature
+methods and Runtime Agent forwarding methods are removed without aliases.
+
+## Rejected alternatives
+
+- Move Agent errors to Engine/common while keeping Agent decisions in Engine.
+- Have Engine construct concrete feature registries or choose coordinators.
+- Move only static references while retaining Workflow-specific maps/dispatch.
+- Split feature and idle locks, allowing shutdown to miss newly admitted work.
+- Invoke arbitrary callbacks without registered receiver and lifecycle rules.
+- Replace OffloadPool physical-completion supervision with new worker threads.