phronomy 0.27.0 → 0.28.0

data/docs/architecture/r8-unit11.md

@@ -0,0 +1,71 @@
+# r8 unit 11: C04 concrete Policy and LLM connection selection
+
+Contract placement follows ownership of meaning and invariants, not reuse.
+This unit addresses review findings B01 and B02: Agent::Base selected the
+concrete DefaultPolicy, and InvocationActions constructed the concrete LLM
+AsyncClient. Neither choice belongs to Agent progress decisions.
+
+| Owner | Responsibility |
+| --- | --- |
+| Agent::Base / C04 | Declare, validate, inherit and use a ContextPolicy |
+| ContextPolicy / C05 | Context-selection operation contract |
+| DefaultPolicy implementation / I01 | Existing selection strategy and token-budget allocation |
+| runtime_composition/agent_defaults.rb / A01 | Install DefaultPolicy through the existing Base.context_policy DSL |
+| Agent InvocationActions / C04 | Prepare the LLM request, request a client through the owning environment, track completion and deliver progress |
+| Agent ExecutionEnvironment | Private connection capability to build an LLM client for the supplied adapter |
+| Agent EngineEnvironment / I07 | Select AsyncClient and bind submission to the captured Runtime |
+| LLM AsyncClient / I06 | Run the complete C09 operation through C13 submission; forward stream chunks and cancellation |
+| LLMAdapter / C09 | Synchronous complete/stream operations and request/response rules |
+
+Ordinary require "phronomy" installs the existing DefaultPolicy instance.
+Base no longer supplies a concrete fallback; an unconfigured root raises a
+ConfigurationError. No supported loading path is left unconfigured. Class
+inheritance and explicit Policy overrides retain their existing semantics.
+Selecting the default does not create configuration, stores or a Runtime.
+This does not change DefaultPolicy's algorithm or introduce a policy registry.
+
+InvocationActions now asks its retained environment for the LLM client.
+It still reads the configured adapter at dispatch time. The Engine binding
+constructs AsyncClient with itself as the existing C13 submitter protocol;
+AsyncClient does not depend on the Agent environment type. No generic factory
+registry, new logical Contract or public application API is introduced.
+
+The client forwards the original TaskResult rather than replacing it. Logical
+cancellation and physical worker completion remain distinct. An explicit pool
+still uses Execution's existing pool-selection protocol and overrides the
+injected submitter. A standalone client with no injected submitter continues
+to resolve the current default Runtime at each call. Client construction
+starts no Runtime resources.
+
+For Agent calls, submission now uses the Agent's captured Runtime, matching
+its sessions and other work. Replacing the default Runtime cannot redirect
+only its LLM worker to a different owner. A stopped owner rejects new work
+through the existing RuntimeShutdownError. Provider errors, admission failure,
+chunk ordering, cancellation and completion are not translated by this change.
+Public Agent/Policy signatures, manifests, durable schemas and recovery rules
+are unchanged. The private AsyncClient constructor adds an optional submitter;
+its private RBS uses the existing _ExecutionSubmitter interface.
+
+## Evidence and remaining scope
+
+Regression tests cover ordinary lazy loading, inherited/explicit Policies,
+complete and streaming Agent calls after default Runtime replacement, live
+adapter selection, provider worker ownership and EventLoop callback ownership.
+Connection tests cover resource-free construction and stopped-owner rejection.
+Async client tests cover the narrow submitter, explicit pool precedence and
+physical completion after cancellation; existing failure/backpressure tests
+remain acceptance gates.
+
+Ruby AST guards reject DefaultPolicy and AsyncClient references in Agent domain
+files. The Ruby/RBS graph gate separately rejects Agent domain dependencies on
+llm_adapter/async and permits the binding connection. Existing lower-level
+reverse-dependency rules remain intact. These checks have the same static
+analysis limitations as the existing architecture tooling; they do not prove
+that all logical Contract dependencies are acyclic or complete.
+
+B01 and B02 are addressed in this candidate. C04 is not declared globally
+complete. Remaining review includes C01 Orchestrator inheritance from the
+concrete Agent tool, C02 Workflow execution connections and separately scoped
+durable child behavior, and Recovery's domain/persistence responsibilities.
+Existing domain-level explicit/configured/default store selection is not itself
+a defect: concrete default persistence factories are already in composition.

data/docs/architecture/r8-unit12.md

@@ -0,0 +1,67 @@
+# r8 unit 12: C01 subagent operations use the C06 Tool contract
+
+Contract placement follows ownership of meaning and invariants, not reuse.
+This unit addresses B03: Orchestrator.subagent generated a subclass of the
+concrete Tools::Agent implementation (I04). The generated class replaced Agent
+creation and child coordination, but inherited Tool operation rules incidentally.
+
+| Owner | Responsibility |
+| --- | --- |
+| MultiAgent / C01 | Define the subagent operation, child class, knowledge/context inheritance, child error policy and durable reconciliation |
+| Agent / C04 | Public child invocation and recovery outcomes |
+| Tool / C06 | Input schema, Tool error policy, result limits and completion-handle requirements |
+| Execution / C13 | Nonblocking completion composition and physical completion propagation |
+| Tools::Agent / I04 | Standalone concrete Agent Tool construction through from_agent |
+
+Orchestrator remains an Agent::Base subclass: a coordinating Agent is a valid
+C01-to-C04 relationship. Its generated subagent Tool now derives directly from
+Tool::Base and explicitly declares cooperative execution and its input schema.
+Generating this domain-owned operation belongs to C01; no runtime registry,
+factory, new logical Contract or composition layer is needed for that operation.
+
+Tool::Base has a private call_async_operation helper that validates inputs,
+requires a completion handle, applies Tool error policy and limits successful
+results. Its block supplies the domain operation. It does not create Agents,
+select implementations, wait for completion or decide how many application
+filters to run. Both the subagent operation and Tools::Agent use this helper.
+The default Tool::Base#call_async path and synchronous-call delegation are
+unchanged, including the unit 9 result-transformation behavior.
+
+ExecutionRehydrationRequiredError remains an Agent-domain outcome. Tools::Agent
+and the C01 operation retain their private pass-through hooks; C06 does not
+reference this error or interpret recovery. Generic errors retain their original
+backtrace when wrapped; ToolError and CancellationError remain unchanged.
+Suppression logging uses C06's existing RuntimeSettings logger capability.
+
+An ordinary asynchronous subagent call still checks cancellation before schema
+validation, starts the child without occupying a waiting offload worker, maps
+its output and applies Tool policy. The subagent on_error option continues to
+control child failure (raise or skip); it is distinct from Tool on_error policy.
+
+An admitted durable child follows the existing reconciliation path directly.
+It is reconciled even with a cancelled parent token; unknown outcomes and
+recovery requirements are not hidden. This path retains its existing validation,
+result and cancellation behavior, without adding the ordinary-call truncation
+or error-suppression pipeline. Agent-owned configured result transformations
+still wrap either path in the configured order, including repeated filters.
+Parent/child IDs, reservations, stores, persistence schemas and recovery rules
+are unchanged. Logical settlement does not falsely imply physical completion.
+
+## Evidence and remaining scope
+
+Non-Agent Tool tests cover asynchronous validation/coercion, errors, result
+limits, cancellation and separate physical completion. Subagent tests cover
+operation without Tools::Agent, ordinary and admitted-child cancellation,
+recovery error identity and repeated transformations after truncation. Existing
+pool-starvation, knowledge inheritance, durable coordination/restart and result
+transformation tests remain acceptance gates.
+
+The AST gate rejects concrete Tools references in C01 domain files and
+Agent recovery interpretation in C06. The Ruby/RBS graph gate rejects C01
+domain-to-tools implementation dependencies. Existing lower-level and Engine
+binding rules remain intact. These are targeted regression checks, not proof
+of all logical Contract dependencies or global acyclicity.
+
+B03 is addressed in this candidate. C02 Workflow execution connections, its
+separately scoped durable child guarantees, and broader Recovery responsibility
+review remain. No completed status is asserted for all of C01/C02/C04.

data/docs/architecture/r8-unit13.md

@@ -0,0 +1,61 @@
+# r8 unit 13: C02 Workflow rules and Engine connections
+
+Contract placement follows ownership of meaning and invariants, not reuse.
+This unit addresses B04: WorkflowRunner and its registry previously selected
+Runtime, built FSMSession instances and constructed Engine event envelopes.
+The phase compiler also contained Workflow callback rules alongside the
+state_machines translation.
+
+| Owner | Responsibility |
+| --- | --- |
+| Workflow / C02 | Topology, callback rules, segment admission, identity/owner checks, hydration, snapshots, persistence outcome classification and recovery-required retention |
+| Workflow runtime binding | Compile topology into state_machines, build/register sessions, select the owning Runtime and translate classified outcomes into terminal decisions |
+| Execution / C13 | Completion handles and receiver lifecycle/routing protocol |
+| Engine | Serial dispatch, atomic delivery, generic FSM execution and terminal gate |
+| Application | State actions, guards, external event correlation and child operation choices |
+
+WorkflowActionRules owns synchronous entry, transition and exit callback
+constraints, optional event arguments and adoption of returned WorkflowContext
+values. The compiler installs these rules as machine callbacks. Initial entry
+callbacks also pass through the rules before reaching the generic FSM session.
+Application callback order remains exit, transition action, entry.
+
+WorkflowExecutionEnvironment is a private C02 connection port. Composition
+installs its provider; WorkflowEngineEnvironment implements it. Compiling a
+Workflow captures its environment without starting an EventLoop, workers or
+execution registration. Starts, durable loads, live signals, terminal saves,
+completion and admission release use that same owner. Changing the default
+Runtime does not silently move a compiled Workflow or its continuations to a
+different owner. Recompile the Workflow after replacing/stopping that Runtime.
+Scalar per-call configuration and configured repository resolution retain their
+existing behavior. Tracing keeps its independent existing execution composition.
+
+WorkflowExecutionRegistry remains in C02. workflow_instance_id, opaque owner
+token and fsm_session_id remain distinct. Routing resolves the current target
+under the existing lifecycle lock; ExecutionReceiverBinding constructs the
+Engine event within the same atomic delivery operation. No new registry or
+public extension API is introduced.
+
+Runner continues to classify terminal persistence results as success, known
+failure or outcome unknown. The binding only translates these outcomes into
+complete, fail or retire instructions. A successful terminal notification still
+requires confirmed persistence. An uncertain outcome still retires the session
+while retaining recovery-required admission; it does not announce success or
+release another owner's segment. Readback/reconciliation does not retry a save.
+Admission is acquired before durable load, and rejected competitors do not load.
+
+## Evidence and remaining scope
+
+Existing tests cover competing admission, immutable terminal snapshots, lost
+responses, unknown outcomes, shutdown, wait/resume, live event routing and action
+ordering. New tests cover standalone callback rules, resource-free compilation,
+owner retention across blocked load/save and default replacement, and rejection
+on a stopped owner. Ruby AST and Ruby/RBS graph checks reject C02-to-Engine or
+C02-to-binding dependencies while preserving lower-layer restrictions.
+
+The targeted C02 execution connection boundary is addressed. This is not proof
+that every logical Contract is complete or that the whole source graph is
+acyclic. F01 durable Workflow children still need an explicit specification for
+identity, reservation, completion persistence and recovery; application actions
+may still launch ordinary asynchronous work. Broader Recovery ownership review
+also remains. No durable child protocol or persistence schema is added here.

data/docs/architecture/r8-unit14.md

@@ -0,0 +1,72 @@
+# r8 unit 14: assign existing recovery rules to their owners
+
+The former private `Phronomy::Recovery` combined Agent operation subjects and
+factual resolutions with general persistence evidence comparison. Sharing a
+file or using the word recovery does not make these one Contract.
+
+| Responsibility | Owner after this change |
+| --- | --- |
+| LLM/Tool subject identity, resolution material, resumability classification | C04 Agent, private `Agent::RecoveryRules` |
+| Revision/snapshot evidence comparison and normalization | C07 Persistence, private `Persistence::SnapshotComparison` |
+| Selection of Workflow evidence and interpretation of pre/post/conflict | C02 Workflow, existing WorkflowRunner |
+| Agent restoration, resolution save/readback and continuation | C04 Agent, existing RecoveryCoordinator |
+| Parent/child coordination and durable reconciliation | C01 MultiAgent, unchanged |
+
+There is no independent Recovery Contract. C14 remains retired; C17 is
+OutputParser. M50/G34 are retired in the current source architecture without
+reusing their identifiers. Historical phase configurations retain their history.
+
+## Behavioral scope
+
+This is a relocation of existing rules and their call sites. No public API,
+persisted schema, outcome value, retry, observer, admission or ownership rule is
+added. Error classes/messages and validation ordering are retained. Ordinary
+framework boot still loads the relocated definitions. The former private
+namespace and file are removed, without a compatibility alias. The existing
+public `Phronomy::ExecutionRehydrationRequiredError` moves to `agent/api` while
+retaining its root namespace, superclass and lazy-loading behavior; it remains
+an Agent-domain outcome, also consumed by delegation callers.
+
+`Agent::RecoveryRules` describes external operation facts as `succeeded`,
+`failed` or `not_performed`. Its `Classification` describes resumability. The
+existing structural `persistence_operation` subject normalization is retained
+to avoid changing accepted input or errors; it does not provide a new generic
+durable operation identity or a new supported Agent resolution operation.
+
+`Persistence::SnapshotComparison` returns `pre_state`, `post_state` or
+`conflict`. It performs no I/O. Workflow supplies authoritative readback and
+intended evidence, handles read errors, and decides completion, known failure
+or recovery-waiting admission retention. In particular:
+
+- An absent record with an absent expected pre revision remains pre-state.
+- Without an explicit post revision, a matching normalized snapshot and a
+  revision different from the expected pre revision identifies post-state.
+- With an explicit post revision, both revision and snapshot must match.
+- Otherwise a matching pre revision identifies pre-state, even if the snapshot
+  differs. The explicit post comparison still precedes this check.
+- Accessors precede symbol keys, which precede string keys. Nested hash keys
+  and symbol values normalize to strings. Read/accessor errors propagate to
+  the owning domain as before.
+
+`Persistence::SaveOutcome` is unchanged. It compares domain-supplied before/after
+evidence using its existing equality and reports `committed`, `not_committed`
+or `unknown`. It is not substituted for snapshot comparison: their predicates
+and error handling differ. Agent-specific execution metadata comparisons also
+remain in Agent.
+
+## Verification and limits
+
+The relocated specs retain existing cases. Additional regressions fix comparison
+priority, normalization, accessor precedence, error identity, resolution error
+ordering and subject immutability. The same 45 primitive examples pass against
+the unit13 definitions and the relocated definitions. Existing Agent recovery
+and Workflow terminal persistence tests cover their surrounding behavior.
+
+AST and combined Ruby/RBS graph gates reject dependencies from other domains on
+Agent recovery rules and domain references in generic persistence comparison.
+These checks guard this boundary, not all possible semantic coupling. Root
+loader wiring and dynamic injection require separate review and runtime tests.
+
+Durable Workflow children (F01) remain deferred feature work, outside this
+responsibility refactor and outside its acceptance criteria. This change does
+not establish global acyclicity or completion of every Contract.

data/docs/architecture/r8-unit15.md

@@ -0,0 +1,65 @@
+# r8 unit15: Generation contract boundaries
+
+This responsibility refactor is based on applied unit14, commit
+`97c3d76b35594bb971a60a2932410ddf22e48d3a` (tree
+`c326196212a4ac369294a9ccb936619813e51250`).
+
+## B05: Agent operation connection
+
+Generation previously used `send(:__invoke_async_with_event_sink, ...)` to
+select Agent's private per-execution listener. It now constructs each Agent
+once with its public `on_event:` option and calls public `invoke_async`.
+
+The private Generation `AgentOperation` owns the connection, not Agent execution:
+
+- Each returned TaskResult supplies that call's terminal result or original
+  failure. Terminal incarnation notifications are not interpreted a second time.
+- Approval remains a listener notification while the Agent TaskResult is pending.
+  Generation retains its existing policy: approval suspension fails the pipeline.
+- Pending submissions retain their Generation listeners in Workflow entry order.
+  Agent continues to own admission. A rejected overlapping call cannot replace
+  another call's approval listener; a queued call may be admitted after the prior
+  result settles. Only the corresponding settled or synchronously failed request
+  is removed. Result callbacks are thread-safe and never wait on the EventLoop.
+- Agent instances and their conversations are reused across iterations and
+  pipeline invocations. No per-call Agent creation, automatic cancellation,
+  retry policy, durable child tracking, or new runtime registry is introduced.
+- The unused private Agent event-sink method is removed. Per-invocation public
+  `on_event:` arguments remain unsupported.
+
+`AgentResultReceiver` and `PipelineState` retain event interpretation, parsing,
+request correlation, stale-result rejection, review feedback and trust decisions.
+Their rule bodies are unchanged. `WorkflowBuilder` retains state definitions and
+entry order. Its private operation port is not a new public Agent API.
+
+The connection relies on existing public Agent guarantees: one admitted
+execution per Agent, ordered incarnation notifications, and TaskResult settlement
+for terminal results. Approval does not settle the TaskResult. Handoff remains
+outside GeneratorVerifier completion semantics, as before.
+
+## B06: Default parser composition
+
+`runtime_composition/generation_defaults.rb` selects the existing JsonParser
+through a private one-time factory binding. Generation lazily creates and reuses
+one default parser per pipeline only when default parsing is needed. Boot creates
+no parser, Agent, Persistence or Runtime for this binding.
+
+Generation owns `default_parse_draft` and `default_parse_review`, including the
+existing ParseError fallback payloads. Existing custom parser callables take
+precedence. No application configuration changes are required. OutputParser's
+contract and its concrete implementations are unchanged.
+
+## Scope and verification
+
+AST regression gates reject concrete parser selection and the removed private
+Agent invocation in Generation. Public-only Agent doubles cover inline completion,
+busy failure, queued admission, stale terminal notifications, timeout, cancellation
+and approval while pending. Real Agent integration covers approval in both phases
+and retained conversations. Domain event-rule tests use the private Generation
+operation port; they no longer pretend a private Agent method is the public API.
+
+Public signatures, result shape, stored schemas, generation/review decisions,
+parser fallback values and default iteration limits are preserved. The internal
+result-observation plumbing changes; this is not merely a physical file move.
+F01 durable Workflow children remain deferred feature work. This checkpoint does
+not certify all framework dependencies or all concrete Engine responsibilities.

data/docs/architecture/r8-unit16.md

@@ -0,0 +1,54 @@
+# r8 unit16: Explicit cancellation subscription ownership
+
+This responsibility refactor is based on applied unit15, commit
+`9aebef9217383cebb7fa3ec8b2d17b5763cd3c5e` (tree
+`fcc1bd3bc72ed611a7d4e9090dcf2391b6bc7471`). It addresses B07 only.
+
+## C13 owns registration lifetime
+
+`Concurrency::ResultSubscriptions#explicit_cancellation` registers the existing
+CancellationToken notification and owns its disposal through `close`. This is
+an internal Execution operation, reusing the existing subscription collection;
+it is not a new public registry or a new Tool implementation.
+
+The existing `cancellation` operation delegates its registration bookkeeping to
+this method and retains its additional `cancelled?` check. Its `Subscriptions`
+subclass retains deadline scheduling. An explicit registration alone neither
+checks an elapsed deadline nor schedules a timer.
+
+CancellationToken still owns callback storage, delivery, exception isolation,
+and private removal. `on_cancel` still returns the token. Public signatures,
+exception types, and the callback behavior are unchanged. In particular, closing
+a registration does not retract a callback already taken by concurrent `cancel!`.
+
+## Consumers retain their execution decisions
+
+- C01 TeamCoordinator registers its existing cancellation callback through C13
+  and closes the collection in the existing `ensure` block. Team still owns the
+  durable cancel request, child cancellation, and terminal outcome interpretation.
+- I09 OffloadPool registers its existing operation cancellation callback through
+  the same operation. It still owns queue/worker admission, logical settlement,
+  deadline promotion, abandonment, and physical completion. Timer registrations
+  are closed before cancellation registrations, preserving cleanup order.
+- C06 Tool already passes its token to the standard offloaded submitter. Its
+  operation dispatch and cooperative/custom-async paths are unchanged. No
+  Tool-specific subscription or symmetric copy of Team logic is introduced.
+
+An already-cancelled token may deliver during registration and close the
+subscription collection before registration returns. The existing collection's
+`add` behavior disposes such a late-added registration immediately. The same
+mechanism covers a concurrent `close` during registration.
+
+## Verification and remaining scope
+
+Behavioral checks cover explicit cancellation, expired deadlines without explicit
+cancellation, inline and concurrent close, delivery already in flight, callback
+failure isolation, and Team/worker cleanup after success and failure. Existing
+OffloadPool timeout, cancellation, and physical-completion tests remain applicable.
+The AST gate rejects private token-removal calls outside Execution, including
+literal reflective calls in Engine and domain code.
+
+B08 configuration access and F01 durable Workflow children are not implemented
+here. Public API/RBS, storage schemas, default configuration, and domain rules
+are retained. This change does not certify all Contract boundaries or eliminate
+the aggregate implementation graph's cycles.

data/docs/architecture/r8-unit17.md

@@ -0,0 +1,73 @@
+# r8 unit17: Domain settings consumption
+
+This responsibility-only refactor is based on applied unit16, commit
+`fb551e1a1a8334b2547ecad126dd9c152c1b0f8c` (tree
+`1ddb3b0e3f4eb97c1738ad02f9035eeefa180c90`). It addresses B08.
+
+## Values and composition have different owners
+
+Agent::Settings owns Agent option values and the existing stream callback error
+policy validation. WorkflowSettings owns the Workflow progress limit and optional
+state repository. They contain actual domain values, never the application
+Configuration object. Their readers do not select a concrete adapter or backend.
+Configuration remains the application-facing facade and composes these values;
+its existing readers, writers, default values and zero-argument constructor remain.
+The application composition boundary supplies the defaults and lazy providers.
+
+The existing MultiAgent::Store receives a provider for the optional configured
+store. It does not construct a fallback. Team still falls back to its fresh-store
+factory; Orchestrator still permits no coordination store unless durable children
+require one. Explicit stores and execution participants keep their priority.
+A single store reader does not require a separate MultiAgent settings class.
+
+Logger reads use the existing neutral RuntimeSettings. Agent authorization pool
+size and queue capacity belong to the execution connection, which reads them
+when submitting authorization work to the owning Runtime. Agent retains timeout
+selection, approval evaluation, result interpretation, and operation supervision.
+The private ExecutionEnvironment#submit_authorization operation separates those
+resource choices from ToolInvocation. Generic Tool submission is unchanged.
+
+## Preserve read timing without notifications
+
+Each existing read remains at its previous execution boundary. Providers are
+bound without evaluating Configuration or starting Runtime resources. A read
+resolves the current domain values; it does not subscribe, poll, cache, or push
+changes. There is no observer, change event, background task, version counter,
+refresh loop, or new in-flight reconfiguration guarantee.
+
+The existing read positions and short-circuit rules remain significant:
+
+- Agent class model fallback is read when model is requested. Explicit class
+  models keep precedence. Already-created Agent stores are not replaced.
+- Hooks and LLM adapter operations are read at the existing input preparation,
+  identity check, and call sites. Hook order and validation remain Agent rules.
+- Workflow limits are read when starting or resuming execution. An admitted
+  execution retains its limit; a changed global default does not update it.
+- Explicit nil, per-invocation overrides, configured stores, and fresh fallback
+  stores retain their existing meanings. No new defaults are created on reads.
+- Configuration copies duplicate the domain value containers while retaining
+  injected component identities, preserving nested scoped overrides and reset.
+
+The new domain value types are internal, grouped by responsibility rather than
+one class per setting. Public Configuration continues to offer the same settings;
+applications do not need to inject every value manually. Its private instance
+variables and internal containers are not an application extension API.
+
+## Verification and limits
+
+Regression checks cover lazy boot and direct Configuration loading, nested scope
+restoration after failure, reset, component identities, nil, class and invocation
+overrides, hook read timing/order, Workflow admission-time limits, persistent
+Agent stores, and the distinct Team/Orchestrator fallback behavior. Execution
+connection tests verify authorization resource options and owning Runtime.
+Existing failure-policy/logging tests configure values through public writers
+instead of mocking the old composition getter. RBS records the new internal
+boundaries without erasing domain operation types.
+
+AST gates reject application Configuration references from Agent, Workflow, and
+MultiAgent domain code, including literal reflective access. They also reject
+pool sizing in domain code. These are targeted regression checks, not a proof of
+all dynamic dependencies or a whole-framework completion claim.
+
+B07 remains applied. F01 durable Workflow children and other feature work are
+outside this change. There are no storage schema or public operation changes.

data/docs/architecture/r8-unit18.md

@@ -0,0 +1,92 @@
+# R8 unit18: durable cancellation receipt
+
+## Problem
+
+An Orchestrator load can return while recovery of a framework-owned child is still
+in flight. If the child needs external factual resolution, Agent captures an
+immutable terminal command that will retain the active parent in coordination
+wait. A cancelled token supplied to `resume` after command capture previously
+cancelled only the live invocation. The earlier command could then persist a
+false cancellation snapshot and release the owner. Restart lost the request.
+
+Controlled scheduling reproduced this in both unit16 and unit17, three times out
+of three. The original example passed 200 natural repetitions. Without the
+applicant's original failure log, equivalence to that initial failure is not
+established. The controlled race is independently demonstrated.
+
+## Ownership
+
+Agent owns receipt of cancellation for an exact execution, its existing durable
+cancellation ledger, and persistence of the parent execution. MultiAgent still
+owns the unresolved-child and pending-parent rules. Execution owns notification
+registration and delivery; Engine owns runtime connections. No Agent decision is
+moved into those mechanisms or into neutral Persistence/Storage.
+
+`ExactExecution` validates identity, reservation, input and participant binding
+before recording a supplied cancellation through `Store#request_cancellation`.
+The write runs in its existing off-EventLoop preparation, before recovery or
+waiting. If cancellation first becomes visible during EventLoop delivery,
+preparation runs again before the live owner is signalled. Recording errors fail
+the observer and do not proceed to recovery or notification.
+
+`ExecutionChange#prepare_in` already reads the monotonic cancellation ledger
+inside the participant transaction. `ExecutionOutcomeCommitter` now uses that
+prepared fact for a pending execution's cancellation metadata. The worker's
+captured command remains immutable; it does not query a live invocation or token.
+
+## Ordering and preserved semantics
+
+- Before outcome commit: the transaction sees the accepted ledger entry and saves
+  cancellation in both Agent pending metadata and MultiAgent extension state.
+- After outcome commit: the ledger retains newly accepted intent without changing
+  execution revision or invalidating the in-flight result. The previously saved
+  metadata/extension remain a snapshot; the next recovery/change incorporates the
+  ledger. Immediate equality between those snapshots and the ledger is not an API
+  guarantee. The ledger is the durable source of accepted cancellation intent.
+- After owner release: receipt records intent before recovery installation.
+- An absent execution is not assigned a cancellation record. A terminal result,
+  including one that wins against cancellation receipt, remains unchanged.
+- Unknown child external outcomes still require factual resolution. No LLM replay,
+  forced child completion or new recovery capability is introduced.
+
+There is no schema change, public API change, new Contract, Registry, subscription
+or polling mechanism. This fixes receipt of cancellation observed by the existing
+exact-execution path; it does not introduce continuous subscription to an incoming
+token after observer registration.
+
+## Verification design
+
+Queue gates hold the outcome worker before commit and after commit/before result
+publication. Gates never block EventLoop or hold a storage transaction. Tests
+assert ledger persistence, unchanged revision during receipt, pending snapshots,
+restart preservation, unknown-child activity and zero LLM replay. Additional
+component tests cover validation rejection, write failure, recovery ordering,
+late token observation and terminal-result preservation. The pending commit test
+also covers committed-response loss.
+
+The original checkpoint fixture now performs phase inspection and snapshot copy
+under one backend lock, preventing concurrent after-commit hooks from replacing a
+selected checkpoint. Its initial assertion uses the durable ledger because a
+request arriving after a saved waiting snapshot need not rewrite that snapshot.
+Separate deterministic tests assert the snapshot on each side of the commit.
+
+## Unit18 delivery correction
+
+The first unit18 version checked the incoming token twice inside delivery: once
+to decide whether to record, and again to decide whether to signal. Cancellation
+between those observations could skip recording but still signal the owner.
+A suspended approval execution then exited without a completion reconciliation,
+leaving the durable ledger empty.
+
+Delivery now uses one cancellation observation for both decisions. After finding
+and validating the current owner, an observed cancellation returns to off-loop
+preparation if unrecorded, or signals the owner if already recorded. The separate
+preparation and delivery observations remain intentional: scheduling between those
+stages can change the token. A notification is never authorized by a different
+observation from the one used to enforce its recording prerequisite.
+
+Regression tests use the real suspended owner, registry and EventLoop. They
+cancel the incoming token just before delivery or during the owner lookup, and
+cover both successful recording and recording failure. They assert recording
+before notification, no notification on write failure, off-loop persistence and
+unchanged suspended execution contents. No polling or new subscription is added.

data/docs/architecture/r8-unit19.md

@@ -0,0 +1,61 @@
+# R8 unit19: Engine resource lifetime
+
+## Confirmed failures
+
+Overlapping first default-pool lookups could construct two pools and retain only
+one. A pool lookup that passed Runtime's state check could also create a pool
+after shutdown had captured its resource list. Both cases left live workers
+outside the claimed completed cleanup.
+
+OffloadPool previously returned after each worker join timeout without reporting
+whether workers remained. Runtime interpreted the absence of an exception as
+successful cleanup. A real blocked worker was still active after the default
+30-second join while Runtime reported terminated, clean and complete.
+
+## Ownership
+
+PoolRegistry owns pool creation, registration and closure of that registration.
+The same mutex protects default and named pool construction and the transition
+to a closed registry. Runtime still admits resources during its draining phase
+for previously accepted continuations. PoolRegistry rejects requests after the
+shutdown resource set is captured, including lookups that passed an earlier
+Runtime check.
+
+OffloadPool owns worker admission and physical worker lifetime. begin_shutdown
+closes admission without waiting and preserves queue draining. shutdown waits
+using one monotonic deadline; its existing self return is preserved. terminated?
+reports that admission is closed and every owned worker has actually exited.
+TaskResult cancellation or timeout is not proof of physical worker termination.
+
+PoolRegistry first closes all pools, then waits outside its registration lock.
+Every pool uses the same absolute deadline. Cleanup continues for the remaining
+pools after an individual error; the first error is propagated after those
+attempts. Runtime still attempts timer cleanup in ensure.
+
+Runtime owns the aggregate decision. Its existing stop-phase deadline is shared
+by EventLoop and pool joins. Cleanup is incomplete while any worker remains;
+domain finalization and default-Runtime replacement remain blocked. Runtime's
+existing cached-result behavior is unchanged: an incomplete result is not later
+promoted to complete by calling shutdown again.
+
+## Scope
+
+This is an Engine lifecycle correctness fix, not only a file relocation. Pool
+shutdown no longer silently reports completed resource cleanup when workers
+remain. The pool waiting budget is shared instead of being restarted per worker
+or per pool. No worker is forcibly interrupted, and queued accepted work still
+drains. Applications retain responsibility for bounded synchronous operations
+and native I/O timeouts.
+
+Agent cancellation persistence, MultiAgent parent/child policy, Workflow
+persistence decisions, C13 result/subscription contracts, settings providers and
+durable formats are unchanged. No new domain Contract or notification mechanism
+is introduced. E03 passive metrics collection remains a separate follow-up.
+
+## Verification
+
+Queue-controlled tests reproduce overlapping first pool creation and lookups
+delayed until after shutdown. Real worker gates verify bounded shutdown,
+incomplete results, retained Runtime, withheld finalization and the difference
+between logical cancellation and physical completion. Additional cases preserve
+draining continuations and ensure all resources receive cleanup attempts.