phronomy 0.25.0 → 0.27.0

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.

data/docs/decisions/043-storage-execution-constraint-notifications.md

@@ -0,0 +1,75 @@
+# ADR-043: Storage-Owned Execution Constraint Notifications
+
+The raw fixed-repository/error portions are amended by [ADR-058](058-neutral-storage-primitives.md). Domain ownership and applicable transaction/uncertainty decisions remain in force.
+
+
+**Status**: Accepted
+**Date**: 2026-09-21
+**Refines**: [033-domain-persistence-ownership](033-domain-persistence-ownership.md) and the Beta Backend error contract in [persistence-backends](../persistence-backends.md)
+
+## Problem
+
+InMemory and the SQLite/PostgreSQL reference backends raised `AgentBusyError`
+for stored nonterminal-execution constraints. A storage implementation therefore
+selected a feature lifecycle exception, even though domain repositories already
+owned record conversion and public operation semantics.
+
+## Decision
+
+`Storage::ActiveExecutionConflictError < Storage::ConflictError` identifies only
+a stored nonterminal execution preventing another admission or an idle-only
+operation for the same owner. It contains no Agent/Team class, domain object,
+callback, or new persisted field. Generic duplicate IDs, stale revisions and
+other precondition failures remain ordinary `Storage::ConflictError` values;
+connection errors and uncertain outcomes retain their existing error types.
+
+Raw execution repositories use this subtype from `create_active`, `assert_idle!`,
+and any existing `save` branch that detects the same active-owner constraint.
+Agent and MultiAgent execution repository facades translate only this subtype
+to the existing public `AgentBusyError`, preserving its message and Ruby cause.
+They do not catch every `ConflictError` or reinterpret database exceptions.
+The existing Team public error remains unchanged; choosing a different Team
+lifecycle exception would be a separate API decision.
+
+Constraint detection and the write remain inside the same backend consistency
+boundary. No preflight lookup is moved above the backend. Domain translation
+occurs inside the existing transaction block so the mapped exception still
+causes rollback before commit. SQL statements, lock order, connection binding,
+indexes, persisted records and transaction boundaries are unchanged.
+
+## Compatibility and migration
+
+This intentionally changes the Beta raw Backend error contract. Callers of
+`backend.executions` and `backend.team_executions` must catch the new storage
+subtype instead of `AgentBusyError`. Callers of the domain-facing Persistence,
+Agent and Team APIs continue receiving `AgentBusyError` for that condition.
+
+The core, InMemory and both reference SQL backends are migrated together. Apply
+the core before the new SQL sources; the new backend sources require the new
+storage constant. An old backend that still raises `AgentBusyError` passes
+through an updated domain facade unchanged, but no longer conforms to the new
+raw SPI. There is no fallback alias in Storage or Engine.
+
+The shared backend suite now checks raw notifications separately from domain
+exceptions, including duplicate-ID and stale-revision distinction and rollback.
+The storage isolation guard removes its former Agent lifecycle file exemption.
+
+## Guarantees and limits
+
+| Subject/property | Provider | Failure/boundary | Result |
+|---|---|---|---|
+| One nonterminal execution per stored owner | Existing atomic admission, backend lock/transaction/DB constraint | F2; no X0 | CONDITIONAL on the backend satisfying the existing atomic_admission contract; no new cross-process owner lease |
+| Uncommitted writes roll back when a mapped constraint escapes | Existing storage transaction with domain conversion inside its block | F0/F2; no X0 | YES for an ordinary known pre-commit constraint failure; not a claim about uncertain commits |
+| Caller-facing busy errors retain their meaning | Feature repository translation of the dedicated subtype | F0/F2; no X0 | YES for the documented domain repository paths; unrelated conflicts are not converted |
+
+This change adds no F1 outcome reconciliation, F4 rehydration, external-effect
+rollback or exactly-once guarantee. The eight repository names and Agent
+watermark that ADR-033 leaves in Storage remain an explicit intermediate state.
+Removing the exception dependency does not make the entire SPI domain-neutral.
+
+## Rejected alternatives
+
+- Move `AgentBusyError` into common definitions or alias it from Storage.
+- Translate every `ConflictError` into a busy error.
+- Check active state in the domain facade before performing a separate write.
+- Migrate only InMemory and silently leave the SQL raw contract inconsistent.

data/docs/decisions/044-agent-default-and-one-shot-composition.md

@@ -0,0 +1,106 @@
+# ADR-044: Agent Default and One-Shot Composition
+
+**Status**: Accepted on the architecture refactoring branch
+**Date**: 2026-09-21
+**Refines**: [038-responsibility-based-source-layout](038-responsibility-based-source-layout.md)
+and [040-configuration-default-composition](040-configuration-default-composition.md)
+
+## Problem
+
+`Agent::Base` selected the concrete default with `Persistence.in_memory`.
+`Agent.run_once`, defined beside Agent lifecycle namespace loading, also selected
+and constructed Persistence. Both files therefore depended on the higher-level
+Persistence composition API, but for different reasons.
+
+Default selection is an injected construction dependency of Agent execution.
+One-shot execution is itself a composition API. Treating both as lower-level
+Agent execution obscured those responsibilities. Replacing one-shot storage with
+the configured shared Persistence would change isolation and existing behavior.
+
+## Decision
+
+1. Agent owns the private `Agent::DefaultPersistence` construction contract. A
+   zero-argument factory is bound once and frozen during application loading.
+   `Base` invokes it only after the explicit `persistence:` and configured
+   `configuration.persistence` values have both been excluded, preserving their
+   existing truthy fallback order. It neither caches the constructed instance
+   nor writes it to configuration. Subclasses consume the same binding.
+2. `runtime_composition/agent_defaults.rb` selects `Persistence.in_memory` in
+   that factory. Binding does not invoke it, create settings, or start Runtime.
+   The binding is not a public plugin registry, an alternative application
+   configuration mechanism, or a new Runtime service locator. Runtime and
+   configuration resets do not replace or reinstall it.
+3. `agent/composition/run_once.rb` owns the actual `Agent.run_once` definition.
+   It remains `Phronomy::Agent.run_once`, with the same parameters, forwarding,
+   result, and exception behavior. It constructs fresh ephemeral Persistence on
+   every call even when global Persistence is configured. It does not consume
+   Base's fallback factory. Rejecting simultaneous `on_event:` and a block still
+   occurs before storage or Agent construction.
+4. `agent/api/agent.rb` retains `StreamEvent` and lifecycle extension loading.
+   It has no delegate to the higher-level one-shot implementation. The
+   application entry explicitly requires the namespace extensions, factory
+   binding, and one-shot method definition after Zeitwerk setup and global
+   configuration access installation. The composition directory and binding
+   file are ignored by Zeitwerk because they wire existing constants rather
+   than introduce matching public namespaces. Agent execution never requires
+   the application entry or either composition file.
+5. Normal application loading, first constant access, repeated requires, and
+   eager loading retain constant identity and exactly one lifecycle extension.
+   Explicit namespace loading also handles the internal unbound factory
+   contract having been loaded first. Arbitrary partial loading of framework
+   implementation files remains outside the public application-loading API.
+
+## Compatibility and guarantees
+
+The public constructor and one-shot API, event callback paths, stored records,
+transaction boundaries, Agent ownership, and shutdown behavior are unchanged.
+The existing API snapshot is not regenerated. It does not cover the `run_once`
+singleton signature, which is checked explicitly along with real invocation,
+creation-time context/Knowledge, and both forms of event listener.
+
+The factory's exception propagates unchanged through the existing Agent
+creation/ownership handling. Classified failures such as ConfigurationError
+release the reservation; unclassified failures such as IOError retain the
+existing fail-closed recovery-required reservation. Do not make every factory
+failure retryable as a side effect of moving default selection. Existing
+explicit Persistence injection works without invoking the factory.
+
+This is source dependency inversion, not removal of the runtime construction
+call: `Base` still invokes the bound factory when a default is needed. The
+one-shot implementation still depends explicitly on Agent and Persistence.
+Both selecting and invoking the one-shot composition remain above execution.
+The private factory slot is immutable after boot; returned Persistence
+instances remain separate, mutable storage instances.
+
+No F1 uncertain-commit reconciliation, F4 recovery guarantee, external-effect
+rollback, or exactly-once guarantee is added. The previous in-memory durability
+limits remain. Runtime retains created Agents according to existing ownership
+rules; moving `run_once` does not introduce new cleanup or lifetime behavior.
+
+## Dependency interpretation
+
+Remove `agent -> persistence/api` and `agent/api -> persistence/api`.
+Add explicit composition dependencies from `runtime_composition` to Agent and
+Persistence and from `agent/composition` to Persistence. One-shot composition
+also calls the injected Agent definition's `create` method; namespace declarations
+and injected calls do not count as static constant-reference edges. The
+`Tools::Agent` call to `Agent.run_once` now targets its actual definition in
+`agent/composition`. Treat the new Agent composition directory as B1; it is
+not a new Ruby namespace.
+The internal Base-to-factory reference remains within Agent's directory.
+
+The remaining reverse dependency `agent -> workflow/execution` is the separate
+worker-input classification change (E). This change does not resolve all
+directory/file cycles, Storage's domain-specific repository names, or the
+Engine FSM terminal persistence responsibilities.
+
+## Verification
+
+Cover fallback precedence, fresh instances and subclass construction, resets,
+classified failure/retry and unclassified fail-closed behavior, supplied-factory
+independence, normal/preloaded/eager
+loading, one-shot isolation from global Persistence, argument/result/exception
+identity, context/Knowledge forwarding, callback conflict ordering, and both
+event listener forms. Run existing Agent ownership/event tests, default and
+integration suites, style, API snapshot, RBS, and annotation gates. Verify
+examples against the changed core without modifying their public call sites.