phronomy 0.26.0 → 0.28.0

data/docs/decisions/033-domain-persistence-ownership.md

@@ -0,0 +1,79 @@
+# 033: Own persistence rules within each domain
+
+- Status: Amended
+- Date: 2026-09-18
+- Error boundary refined by: [043-storage-execution-constraint-notifications](043-storage-execution-constraint-notifications.md)
+- Refines: [032-storage-backend-composition](032-storage-backend-composition.md)
+
+The raw fixed-repository/error portions are amended by
+[ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable
+transaction/uncertainty decisions below remain in force.
+
+## Context
+
+ADR-032 separated raw storage from domain persistence, but the common-looking
+`persistence/` directory still collected Agent, Team, and Workflow schemas and
+repository facades. Moving that directory to an upper band in a dependency
+diagram described its contents; it did not establish suitable domain ownership.
+The public Persistence entry point also contained domain-specific result queries.
+
+## Decision
+
+1. `agent/persistence/` owns AgentRoot, Journal, AgentExecution, and Handoff
+   codecs/repositories and Agent/Handoff result queries.
+2. `multi_agent/persistence/` owns TeamRoot and TeamExecution codecs/repositories
+   and Team result queries. Team persistence can be used over a raw backend
+   without loading Agent implementation or the combined Persistence service.
+3. `workflow/persistence/` owns the Workflow record schema, normalization rules,
+   and state repository. Workflow symbol normalization remains specific to that
+   domain; other codecs do not adopt it implicitly.
+4. `Storage::RecordCodec` contains shared record-envelope and scalar validation.
+   Domain codecs extend it; it neither selects nor imports a domain codec.
+   These helpers and domain components are private implementation, not new SPI.
+5. `PersistenceComposition::Repositories` explicitly assembles the seven domain
+   repository wrappers and the existing ContentStore from one raw storage view.
+   The public `Phronomy::Persistence` service remains the compatible entry point.
+   It delegates queries and retains the Runtime observation-thread guard.
+   Each view creates and caches domain wrappers on first use, under one lock,
+   so Agent-only use does not load Team or Workflow implementations.
+6. Conversion remains inside `backend.transaction`. Root and transaction paths
+   use the same builder. Reusing the root view when the backend yields itself
+   retains the existing repository identity and fault-injection behavior.
+7. Delete the private combined `Persistence::DurableCodec` and
+   `Persistence::RepositoryFacades`; do not preserve a second owner through
+   compatibility aliases. Explicit historical migration keeps its public API
+   and calls the new domain codecs.
+
+InMemory, SQLite, and PostgreSQL are all concrete implementations of the common
+Backend contract. Domain repository wrappers are consumers of that contract;
+they do not introduce a second physical transaction boundary.
+
+## Preserved contracts and limits
+
+Public Persistence methods, Backend SPI, eight repository accessors, IDs,
+revisions/positions, active constraints, physical SQL schemas, record types,
+format versions, and payload schemas are unchanged. Existing SQL backends need
+no source migration for this ownership change. The public result-reader dispatch
+and observation guard remain in the public entry point.
+
+Atomic durable-state transitions and rollback remain CONDITIONAL on a conforming
+backend for F0. Commit-outcome certainty under F1 is not added. F4 restart
+readability depends on retained confirmed data; InMemory is not disk retention.
+X0 effects remain outside storage transactions.
+
+The raw `Storage::Repositories` still names eight Phronomy record repositories and
+an Agent watermark operation. This is an explicit intermediate state, not a claim
+that the framework contract is domain-neutral. Contract generalization and naming
+of the final common persistence framework are deferred to the staged plan below.
+
+## Validation
+
+Existing record-schema, backend conformance, optimistic conflict, recovery,
+Handoff, Team, Workflow, and public compatibility tests remain required. A
+separate-process boundary test uses Team persistence without Agent, Workflow,
+Runtime, or combined-Persistence loading. Another process uses the public Agent
+repositories without loading Team or Workflow implementations. A failure-injection test rejects the
+Team response after writes and verifies rollback across Agent, Team, and content.
+Dependency analysis must not introduce a new nontrivial file cycle.
+
+See [the staged implementation plan](../architecture/persistence-refactoring-plan.md).

data/docs/decisions/034-handoff-runner-coordination-ownership.md

@@ -0,0 +1,78 @@
+# ADR-034: Handoff Runner Coordination Ownership
+
+> r8 unit 4 supersedes the Agent/Handoff ownership and storage portions below. See [the unit 4 migration](../migrations/r8-unit4.md). Earlier statements describe their original change only.
+
+## Status
+
+Accepted for the H1 step on `refactor/architecture`, 2026-09-18.
+The subsequent Handoff contract and persistence separation is deferred.
+
+## Scope of supersession
+
+This amends the Runner placement/public namespace in
+[030-agent-handoff-domain-and-durable-responsibility](030-agent-handoff-domain-and-durable-responsibility.md)
+and the domain map in
+[031-durable-multi-agent-coordination](031-durable-multi-agent-coordination.md).
+All other durable Handoff semantics remain in force.
+
+## Context
+
+HandoffRunner validates a graph of concrete Agents, selects the active Agent,
+invokes or resumes exact executions, follows multiple transfers, and scopes
+cancellation/result lookup to a specified chain. Those responsibilities span
+Agents. They differ from an individual Agent's execution, Journal and Context.
+
+Calling Handoff from an Agent does not make that whole coordination lifetime an
+Agent implementation detail. Updating the Source and routing state in one
+transaction also does not require them to occupy one module.
+
+The Runner and TeamCoordinator share the Runtime-local AdmissionRegistry. Keeping
+the Runner inside Agent creates an Agent-to-MultiAgent concrete dependency.
+Moving only the Runner aligns ownership without generalizing the registry or
+changing the existing shutdown participant contract.
+
+## Decision
+
+1. Move the public Runner implementation from `agent/handoff_runner.rb` to
+   `multi_agent/handoff_runner.rb` and expose
+   `Phronomy::MultiAgent::HandoffRunner`.
+2. Remove `Phronomy::Agent::HandoffRunner` without a compatibility alias on the
+   refactoring branch. Migrate API documentation, RBS, snapshot and consumers
+   together. See the [migration guide](../migrations/handoff-runner-multi-agent.md).
+3. Retain `Agent::Handoff`, `HandoffPolicy`, Context/Request/State and Agent
+   terminal/persistence integration during H1. Qualify the Runner's dependencies
+   explicitly. This mixed placement is an intermediate state.
+4. Keep AdmissionRegistry in MultiAgent. The admission key, exception classes,
+   successful-call release and Runtime shutdown participation are unchanged.
+5. Preserve method parameters/results, record formats, main-Agent anchor,
+   deterministic Target IDs, transaction boundaries, exact recovery and scoped
+   cancellation. H1 introduces no new execution or shutdown manager.
+
+## Consequences and limits
+
+Agent no longer directly names a MultiAgent implementation in production source.
+The Runner's existing Tracing dependency now belongs to the MultiAgent directory.
+Module-edge totals and large strongly connected components need not decrease:
+this step changes responsibility placement, not the underlying algorithm.
+
+Agent still interprets Handoff/Team coordination metadata. This logical coupling
+is not removed merely because a directory edge disappears.
+
+Later work must separate Request construction, Coordinator selection, Context
+conversion, transaction participation and purge/recovery constraints before
+moving the remaining Handoff-specific types and persistence rules. That work must
+preserve one transaction for Source termination plus responsibility transfer and
+for Target termination plus routing stabilization. It must not promote transferred
+Context into permanent Target Journal/Knowledge or depend on post-commit callbacks
+for coordination correctness.
+
+## Verification obligations
+
+The new public constant must load with Zeitwerk and match its RBS/API snapshot;
+the old constant must not remain as an alias. Existing Handoff, multi-hop,
+cancellation/recovery, shutdown and SQLite reconstruction scenarios must pass.
+API guards must distinguish `MultiAgent::HandoffRunner` from the removed exact
+constant `MultiAgent::Handoff`.
+
+The implementation delivery records test results separately; this ADR does not
+assert that unexecuted live-LLM or database-server tests passed.

data/docs/decisions/035-tool-executor-capability-ownership.md

@@ -0,0 +1,68 @@
+# ADR-035: Default Tool Executor Ownership
+
+## Status
+
+Accepted on the architecture refactoring branch as T1.
+
+This decision assigns the default Tool execution helper to the existing
+Capability implementation. The public Tool facade defined by ADR-015 remains
+the same Class object with the same canonical implementation name.
+
+## Context
+
+`Agent::Context::Capability::Base#call_async` delegates default asynchronous
+dispatch to `Agent::ToolExecutor`. The helper selects inline cooperative work
+or OffloadPool submission and returns a TaskResult. It has no responsibility
+for Agent state, approval, persistence, recovery, or multi-Agent coordination.
+
+Placing this helper directly under Agent makes the Capability directory depend
+on Agent execution while Agent execution also depends on Capability. The
+underlying helper is part of the Tool calling contract and its standard
+implementation, so its ownership should reflect that role.
+
+Moving only the helper to `tool/` would introduce another directory cycle:
+`tool/base.rb` currently aliases `Agent::Context::Capability::Base`. Moving the
+canonical Tool class and changing its runtime name would require a separate
+public compatibility decision.
+
+## Decision
+
+1. Move the helper to
+   `Phronomy::Tool::ToolExecutor`, in
+   `agent/context/capability/tool_executor.rb`. Classify this helper as private
+   API and remove the old internal constant without a compatibility alias.
+2. Use the new helper from Capability Base and Agent ToolInvocation. Preserve
+   the existing dispatch implementation and error messages.
+3. Keep `Tool::Base` and `Agent::Context::Capability::Base` as the same Class
+   object. Preserve their canonical name, DSL state, method-owner checks, and
+   the public `call_async(args, cancellation_token:, config:)` protocol.
+4. Keep Runtime selection, authorization and logical result ownership in Agent
+   ToolInvocation. Its standard path passes Runtime and `on_full: :raise` to
+   the private helper; custom Tool implementations receive the public protocol.
+   Agent-as-Tool continues through its own asynchronous Agent lifecycle.
+5. Keep the existing TaskResult and OffloadPool mechanisms in Engine. This
+   step adds no execution manager or application registration requirement.
+
+## Consequences and limits
+
+The Capability directory now directly names its existing Engine dependencies
+instead of an Agent-owned wrapper. The code-level algorithm and file-level
+dependency graph are preserved when the moved file is matched to its source.
+Directory placement changes do not imply that all larger dependency cycles
+have been resolved.
+
+Applications should use the public Tool authoring and invocation contracts.
+Code or tests that directly reference the removed private Agent::ToolExecutor
+constant need to follow its new internal name. The public Tool API and durable
+formats require no migration, and the Context contract regrouping remains a
+separate change.
+
+## Verification obligations
+
+Verify cooperative execution, OffloadPool dispatch, cancellation propagation,
+Runtime injection, custom `call_async`, and Agent-as-Tool. Keep the existing
+offload-boundary observations aligned with the moved source path. The public
+API snapshot, RBS and Tool class identity must remain unchanged; Zeitwerk must
+load the new helper and leave the old internal constant absent.
+
+The implementation delivery records its actual test results separately.

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,145 @@
+# ADR-038: Responsibility-Based Source Layout
+
+> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
+> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
+> construction/interception; Tool owns canonical schema validation. See
+> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
+
+
+## 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.
+
+## Amendment: neutral runtime settings
+
+[060-runtime-settings-and-application-configuration](060-runtime-settings-and-application-configuration.md)
+amends configuration placement and Engine access: application configuration and
+global accessors belong to `runtime_composition/`, while `configuration/` owns
+only neutral `RuntimeSettings`. Concrete defaults remain composition-owned;
+public configuration and Runtime reset behavior 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,82 @@
+# 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.
+
+## Amendment: neutral runtime settings
+
+[060-runtime-settings-and-application-configuration](060-runtime-settings-and-application-configuration.md)
+amends configuration placement and Engine access: application configuration and
+global accessors belong to `runtime_composition/`, while `configuration/` owns
+only neutral `RuntimeSettings`. Concrete defaults remain composition-owned;
+public configuration and Runtime reset behavior remain unchanged.
+
+## 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.