phronomy 0.25.0 → 0.27.0

data/docs/architecture/agent-configuration-and-tool-binding.md

@@ -0,0 +1,139 @@
+# Agent configuration and Tool binding (R09, first slice)
+
+## Role and boundary
+
+Agent::Base is the public declaration and lifecycle facade. Before tools are
+advertised to an LLM or installed in a runtime chat, its prepare_tool_class hook
+selects the Agent's alias and result filters for the original Tool class.
+ToolDefinitionSet and runtime projection installation use that same hook.
+MultiAgent::Orchestrator overrides it, calls super, then adds subagent context.
+
+Previously the hook also generated both decorator subclasses and bridged custom
+asynchronous results, including cancellation and physical completion. Refactor 42
+extracts that mechanism into Agent::ToolBinding in agent/tool_execution. Base
+retains the selection hook and its invocation keyword for Orchestrator cooperation.
+ToolBinding takes an explicit Tool class, alias and filter list; it holds no Agent
+reference and does not call private Agent methods back through send.
+
+| Owner | Responsibility |
+|---|---|
+| Base / Filterable | Select the original class's alias and ordered class, instance and scoped filters. |
+| ToolBinding | Construct alias/result-filter decorators, preserve effective Tool names, and bridge custom async results. |
+| Capability::Base / ToolExecutor | Default Tool call protocol and physical execution. |
+| ToolInvocation | Validation, authorization, execution supervision and state restoration. |
+| Orchestrator | Capture subagent parent/config/knowledge context after Base preparation. |
+
+There is one new internal class and one production file. ToolBinding is marked
+@api private, like other Agent implementation collaborators; it is not a new
+supported application API. No loader change, mixin, alias or public signature
+change is introduced. Definitions, approval, durable schemas and stored Tool
+state are unchanged.
+
+## Preparation and reading order
+
+Base first returns non-Class values unchanged. For classes it constructs the
+alias binding, then resolves filters, then prepares the filtered class. This
+order preserves subclass creation before filter selection. With neither alias
+nor filters the exact original class is returned. With an alias and no filters,
+the alias subclass is returned without instantiating a Tool.
+
+ToolBinding#prepare reads the effective name and the call_async method owner,
+then defines the synchronous decorator and, only when needed, the custom async
+decorator. filter_async_result registers physical and logical completion in that
+order. propagate_failure and complete_filtered_result separate terminal outcomes.
+The methods express one level below their operation names rather than leaving
+the whole callback protocol inside Base.
+
+The original Tool class remains the scoped-filter key even when an alias creates
+a subclass. Each preparation captures a newly collected filter list; it does not
+cache generated classes or deep-copy filter objects. Later registrations affect
+later preparations. The synchronous call passes the original args/keyword values
+to super and applies class, instance and scoped filters in that order, with the
+effective name and original args. Filter exceptions propagate without ToolError
+wrapping by this decorator.
+
+## Asynchronous contract retained
+
+- If call_async is owned by Capability::Base, leave it inherited: its ordinary
+  execution path reaches the decorated call. A second async filter wrapper would
+  apply the same filters twice.
+- Any other method owner, including an inherited custom implementation, receives
+  the custom async decorator. It forwards args/kwargs to super and wraps the
+  returned operation in PhysicalCompletionTask. It does not wait for completion.
+- Preserve logical completed/failed/cancelled status, values and error identity.
+  Failure skips filters. A filter StandardError fails the derived result with
+  that same exception. A synchronous startup exception still escapes call_async.
+- With on_physical_complete support, forward that signal independently of the
+  logical result. Logical cancellation/failure must not fabricate physical
+  completion while the source is still working. Physical completion can precede
+  the logical callback or already be true when the listener is registered.
+- Without that signal, mark physical completion before settling the derived
+  result, including filter failure. Listener registration remains physical first,
+  logical second, so already-settled operations are handled by existing callbacks.
+- Cancelling the derived result does not cancel the source. A later successful
+  source completion can still execute result filters, while its derived status
+  remains cancelled. This is existing behavior, not a new cancellation guarantee.
+
+No retry, additional cancellation propagation, thread/pool policy or physical
+completion guarantee is added. The source signal still describes source work,
+not a new synchronization boundary around the filter callback itself.
+
+## Agent declaration inheritance as currently implemented
+
+Do not infer one uniform inheritance rule from the word "configuration". The
+following describes current compatibility behavior; Refactor 42 does not change
+the DSL methods. Parent reads are live lookups, not snapshots taken at subclass
+creation.
+
+| Declaration / getter | Child without an own value | Own value / special behavior |
+|---|---|---|
+| model | Global configuration.default_model; does not read parent's model | Truthy setter, nil/false are reads. Global changes remain visible until an own value is set. |
+| instructions | Parent instructions, including the same Proc or template object | Text or block replaces the own value. nil without a block is a read, not a clear. |
+| provider | Parent provider | Truthy setter; nil/false read. |
+| tools | Parent tools array by reference | A Hash replaces the own class list. An empty Hash is an explicit empty list. nil reads. |
+| tool_aliases | Parent aliases merged with own aliases | Alias values are stringified; nil entries are omitted. A child nil alias or empty tools list does not erase inherited aliases. |
+| context_policy | Parent policy object, ultimately ContextPolicies::Default.instance | Exactly one ContextPolicy object replaces it. nil is invalid, not reset. |
+| temperature | nil; does not inherit | Truthy setter; zero is accepted; nil/false read. |
+| max_iterations | 10; does not inherit | Truthy setter; zero is accepted. |
+| cache_instructions | nil; does not inherit | nil reads, false is an explicit value. |
+| max_output_tokens | nil; does not inherit | nil reads; positive Integer conversion. context_window moved to the RubyLLM registry in Refactor 45. |
+| agent_definition | Raises until that class declares identity/revision | Each subclass requires its own definition; this is not inherited model configuration. |
+| input/output/tool_result_filter registries | Empty class registry; do not inherit | Registrations append on that class. Instance filters are separate. |
+| before_llm_input / _before_llm_input | nil class callback; does not inherit | Instance and global hook behavior remains separate. |
+
+The generic Agent rule does not override specialised subclass DSL such as
+Orchestrator's subagent registry. Tool/Capability declaration inheritance is also
+a different contract, already covered by its configuration-inheritance tests.
+
+The existing test description that said "normal class configuration still
+inherits" referred only to instructions and was too broad. It now names the
+actual checked rule. No new policy is inferred from that earlier wording.
+
+For compatibility, retain these rules in this source refactor. Uniform parent
+fallback, alias removal and copying inherited mutable values would be separate
+behavior changes requiring an explicit migration decision. They can change
+model/provider combinations, budgets, Tool names and application callbacks.
+
+## Verification and remaining R09 work
+
+Thirty-five new contract examples run against both the unchanged Refactor 41 and
+the candidate. They exercise selection/alias order, names, filter ordering,
+forwarded object identity, default/custom async behavior, logical/physical
+completion, cancellation and DSL inheritance. Existing Tool definition, approval,
+Orchestrator and full integration suites cover the cooperation paths.
+The release, API/SPI, RBS, style, isolated gem and examples gates are recorded in
+the distribution. Candidate remote CI, live PostgreSQL, live LLM and performance
+are not measured by this change.
+
+Refactor 42 is applied and independently verified at core 4a57a3c2. This
+completes the Tool binding and declaration-contract slice. Refactor 43 addresses
+the original Chat construction and explicit state-mutation scope; see the
+[Chat/state design](agent-chat-and-state-ownership.md). It preserves the Base
+hooks and operation/publication order rather than changing DSL semantics.
+
+Refactor 43 application was verified at core 5c4c0392; R09 is closed.
+R10 is implemented in Refactor 44, pending application verification.
+The published SVG is applied43-01. See the [naming boundary](entry-action-and-team-wording.md)
+and the separate [open Tool schema finding](tool-schema-recording-gap.md).
+
+Refactor 45 changes the token declarations as described in [the migration](rubyllm-2-token-ownership.md). Other Agent inheritance rules above remain unchanged. Tool schema/provider configuration follows the RubyLLM 2 inherited configuration contract.

data/docs/architecture/agent-context.md

@@ -84,8 +84,10 @@ See [Context Management](context-management.md) and
 ## 3. Live mutable ownership
 
 Within one Runtime/process, one mutable live Agent instance owns one `agent_id`.
-Loading or creating a second mutable live instance for the same `agent_id` is
-rejected.
+`Agent::OwnershipRegistry` reserves that identity before materialization;
+Runtime strongly retains the registry through the generic shutdown contract.
+Repeated load returns the same live instance, while duplicate create is rejected.
+See [ADR-041](../decisions/041-feature-owned-identity-registries.md).
 
 During active execution, EventLoop is the single writer of Phronomy-managed live
 Agent execution state. Blocking Persistence work and other synchronous work that
@@ -133,7 +135,7 @@ reconcilable
 resolution_required
 ```
 
-Recovery does not restore the old Ruby object graph or old Task callbacks. It
+Recovery does not restore the old Ruby object graph or old TaskResult callbacks. It
 reconstructs current logical state from durable evidence and continues only
 when authority and outcome certainty permit it.
 

data/docs/architecture/agent-transition-ownership.md

@@ -0,0 +1,89 @@
+# Agent invocation transition ownership
+
+## Role and scope
+
+An Agent invocation moves between preparation, Provider calls, Tool processing,
+approval suspension and completion. Three collaborators need the same policy:
+AgentInvocation consumes external payloads; PhaseMachineBuilder creates the
+executable state machine; AgentInvocationSessionBuilder configures FSMSession's
+advance, wait and terminal boundaries. Independently maintained event lists and
+transition copies could disagree about what the current phase can accept.
+
+Refactor 39 gives that shared policy one private owner, InvocationTransitions in
+agent/execution. This is Agent data in the existing transition Hash format, not
+a new cross-feature DSL or Engine extension. It is not a new execution object.
+
+## Ownership and reading order
+
+| Owner | Responsibility |
+|---|---|
+| InvocationTransitions | Initial phase, declared/automatic/approval-wait states, Tool event vocabulary and ordered external transition definitions. |
+| PhaseMachineBuilder | Translate those external definitions to state_machines; retain automatic state_completed transitions and synchronous entry-action validation. |
+| AgentInvocationSessionBuilder | Assemble the invocation, event sink, entry actions and machine; pass shared state and transition metadata to FSMSession. |
+| AgentInvocation | Apply payloads and expose the current guard predicates; use the shared Tool event vocabulary. |
+| FSMSession | Generic advancement, event delivery and wait/terminal handling. No Agent-specific decisions. |
+
+Read the policy table for legal external sources and guard priority, the machine
+builder for execution mechanics, and the session builder for action wiring.
+The EXTERNAL_EVENTS Hash, each transition array and each row are frozen so one
+session cannot edit another session's policy. Guard lambdas contain no captured
+invocation state; they inspect the context supplied at transition time.
+Old private constants and the external_events factory are removed without aliases.
+
+## Preserved event and phase contract
+
+The six Tool events are authorized, approval_required, completed, failed,
+rejected and cancelled, each with the tool_ prefix. Each moves waiting_for_tools
+to evaluating_tools. LLM completion from calling_llm tries these in order:
+
+1. callback_failed? to failed;
+2. handoff_failed? to failed;
+3. handoff_requested? to handed_off;
+4. tool_call_pending? to starting_tools;
+5. unconditional fallback to output_filtering.
+
+Guards short-circuit. A nil context skips guarded rows and takes the fallback;
+guard exceptions propagate unchanged. Each evaluation uses the latest context,
+without caching a selected destination. Session applies the event payload first.
+
+LLM failure/setup failure leads from calling_llm to failed. Tool setup failure
+leads from dispatching_tools to failed, while tool_dispatch_prepared returns it
+to evaluating_tools. Resume moves suspended to waiting_for_tools. Application
+callback failure is accepted from the existing nine active phases only.
+
+Automatic phases remain idle, filtering_input, building_context, starting_tools,
+evaluating_tools, recording_tool_results and output_filtering. calling_llm,
+waiting_for_tools and dispatching_tools wait for external events. suspended ends
+a segment with halted; resume uses a fresh Session identity. The four declared
+terminal phases remain handed_off, completed, blocked and failed.
+
+FSMSession reads only the from field when determining external-event admission
+and waiting. It does not execute metadata guards or choose their destinations;
+state_machines does that. Known-but-undeclared and unknown events retain their
+existing error behavior; context-consumed stale events retain their early exit.
+The internal order of event registration now follows the shared table. Transition
+order within each event, which determines behavior, is preserved. The generated
+machine's private event-enumeration order is not a supported public contract.
+
+## Verification and limits
+
+Independent behavioral tests run on both Refactor 38 and the candidate: all 195
+external-event/source-state combinations, all sixteen LLM condition combinations
+including short-circuit order, nil context and guard exceptions, fifteen Session
+boundaries, context-before-guard ordering, approval suspension/resume/dispatch,
+and invalid source-state handling. Existing Agent, causal durability, Handoff,
+Workflow and Engine tests continue to cover their collaborating behavior.
+
+The candidate also runs the full core/integration suites, offline examples and
+real SQLite, API/SPI snapshots, RBS, style, annotations and isolated gem checks.
+No SQL, stored format, entry action implementation, Tool restoration, cancellation
+or Coordinator sequencing is changed. The new contract tests isolate entry actions
+and do not claim live Provider coverage. Live PostgreSQL/LLM and remote CI are
+not executed for this candidate. Refactor 39 was independently verified after application at core 4d57614a,
+tree 654241da4b2b7f32d988602d28127bc1fa155641. All 10 files and the full tree
+matched, and core/integration/examples/SQLite/API/type/gem checks passed.
+The published SVG is applied39-01.
+
+R06 is applied and complete. R07 now has a Refactor 40 candidate; R08/D08, R09
+and R10 remain afterward. R09's inheritance behavior and R10's action names
+are not altered by the transition-ownership work.

data/docs/architecture/before-llm-input.md

@@ -33,6 +33,12 @@ not receive a mutable Provider chat/message array.
 
 A hook returns `Phronomy::Agent::LLMInputPatch` or `nil`.
 
+These two types live in the shared `agent/context_contract/` implementation
+directory together with the Policy input and result contracts. Zeitwerk
+collapses the directory, preserving their existing public `Phronomy::Agent`
+names. Hook registration, invocation, and result handling are unchanged; see
+[ADR-036](../decisions/036-context-contract-ownership.md).
+
 ```ruby
 Phronomy::Agent::LLMInputPatch.new(
   model_config_patch: {temperature: 0.2},

data/docs/architecture/context-management.md

@@ -50,6 +50,36 @@ RubyLLMMaterializer
 The normative Journal/Manifest split is
 [ADR-012](../decisions/012-canonical-execution-log-and-context-policy.md).
 
+### Contract ownership and physical layout
+
+The contracts shared by Agent execution, Context policies, and input hooks live
+in `lib/phronomy/agent/context_contract/`:
+
+| Files | Responsibility |
+|---|---|
+| `context_policy.rb`, `context_policy_input.rb` | Policy protocol, helper methods, and typed input material |
+| `context_plan.rb`, `context_plan_validator.rb` | Policy result and its validity rules |
+| `llm_input_manifest.rb` | Final logical input representation and its format validation |
+| `llm_input_build_context.rb`, `llm_input_patch.rb` | Input metadata and returned customization for hooks |
+
+Zeitwerk collapses this directory. The Ruby constants keep their existing
+`Phronomy::Agent::*` names; there is no `ContextContract` namespace or new
+registration mechanism. Applications continue to load `phronomy` and use the
+documented constants. The previous individual implementation file paths are
+not retained as forwarding files.
+
+`ContextPolicies::Default` remains a concrete strategy, while
+`ContextAssembler`, input builders, candidate resolution, Runtime connections,
+and persistence transactions remain on the execution side. The Manifest
+validates and converts record values; it does not write to a storage backend.
+Its format version, keys, and validation rules are unchanged.
+
+This ownership decision is defined by
+[ADR-036](../decisions/036-context-contract-ownership.md). Physical containment
+under `agent/` does not assign the contracts to the execution layer. The
+concrete policies and the shared contracts can occupy distinct groups at the
+same abstraction level.
+
 ## 2. Public Context Policy SPI
 
 Application code supplies an ordinary reusable Ruby strategy object:

data/docs/architecture/context-preparation-steps.md

@@ -0,0 +1,90 @@
+# Context preparation steps
+
+## Role and scope
+
+ContextAssembler prepares the immutable semantic input supplied to Application
+ContextPolicy and later validates and stores its decision as an LLMInputManifest.
+InitialPreparation and DispatchPreparation run preparation outside their commit
+transactions, recheck durable state, then call finalize in the commit transaction.
+The public boundary and those callers already have separate responsibilities.
+
+R07 addresses a narrower readability problem inside prepare_initial and
+prepare_followup: orchestration was mixed with individual item IDs, provenance
+and metadata, and record filtering plus Hook/Handoff merging were duplicated.
+The original proposal calls for private extraction before adding collaborators.
+Refactor 40 follows that limit: one production file changes; no class is added.
+
+## Reading order and responsibilities
+
+| Private operation | Responsibility |
+|---|---|
+| initial_instruction_items | Choose the initial Agent instruction and optional Handoff responsibility, in order. |
+| agent_instruction_item | Build the required system instruction with its stable ID, estimate and Agent provenance. |
+| handoff_instruction_item | Build the required user responsibility with its ID, estimate and Handoff origin. |
+| retained_instruction_items | Read only retained base instructions from the previous Manifest, using the existing compatibility predicate and converter. |
+| resolve_record_candidates | Filter working records by eligibility/current generation and resolve them with Journal candidates and caller-provided exclusions. |
+| merge_context_candidates | Add Hook candidates, then Handoff candidates, using the existing creation, sorting and storage operations. |
+| current_input_item | Build the initial required ask argument after all candidates, including ID, sequence, provenance and metadata. |
+
+Public preparation keeps model/Tool settings, source loading and the sequence of
+these operations visible. Record collection and candidate augmentation stay as
+two steps: follow-up computes its next call sequence after record resolution,
+exactly as before. No new options object, pipeline DSL, mutable preparation state
+or cross-feature factory is introduced. Helpers remain private to the assembler.
+
+## Preserved contracts
+
+- Initial instructions come from the Agent configuration plus optional Handoff
+  responsibility. Follow-up instructions come from the retained base Manifest.
+  Current Hook instructions are rebuilt; previous Hook/Policy-generated items
+  do not become permanent base instructions. Legacy origin handling is unchanged.
+- Working records must remain context candidates in the active transcript
+  generation. Initial preparation excludes the current input record; follow-up
+  includes eligible working records without that exclusion.
+- Record candidates are resolved before Hook and then Handoff augmentation. The
+  current-input sequence follows all candidates, including non-conversation ones.
+  IDs, source fields, trust metadata, estimates, required flags, ordering, frozen
+  values and delivery modes retain their existing values.
+- Initial input content is loaded before instruction-item construction and
+  candidate resolution. Initial instruction callbacks and patch normalization
+  retain their order. Hook content writes still precede Handoff type validation;
+  moving that validation earlier would be a behavior change and is not included.
+- Preparation is not side-effect-free: Hook/Handoff content may be stored before
+  Policy succeeds. This extraction neither adds rollback nor suppresses existing
+  exceptions. Missing-input, reserved-metadata, resolver and Policy failures keep
+  their ordering; collaborator exception objects propagate unchanged.
+- Application Policy executes once during prepare; finalize does not invoke it.
+  Finalization, its validation/encoding/store helpers, assembly policy version 8,
+  schemas, public signatures and transaction-owning callers are unchanged.
+
+The new helpers use the same constructor field evaluation and call ordering.
+They do not cache or deduplicate reads, normalize values earlier, or move work
+across the prepare/finalize boundary merely to shorten the source.
+
+## Verification and trade-off
+
+Ten behavior examples cover initial item provenance/immutability, generation and
+exclusion rules, content-write order, absent instructions/Handoff, follow-up
+retention and current hooks, the prepare/finalize boundary and failure precedence.
+The same examples pass on Refactor 39. Four independent baseline/candidate
+scenario pairs compare complete Policy input, Prepared values, Manifest bytes and
+content references, plus preparation-time content read/write order. The pairs
+cover initial and follow-up calls with/without base instructions and Handoff.
+
+Full core/integration suites, common examples and real SQLite, stable/beta API
+and Storage SPI snapshots, RBS, style, annotations and isolated gem checks are
+also run. Live PostgreSQL, live LLM, remote CI and performance are not exercised
+for this candidate; prior CI is not evidence for the candidate's core.
+
+prepare_initial is 103 -> 55 lines and prepare_followup 57 -> 47. The whole file
+is 625 -> 672 lines because seven named private methods and explicit arguments
+add structure. This is a readability and duplicated-procedure improvement, not a
+net line-count reduction or a directory-cycle change. The methods' names give
+readers a place to choose whether they need the detailed representation.
+
+R07 was independently verified after application at core b3dfbc5a, tree
+dcd9d1bf8efb1b488f9c2b3b1c4e99bdeda6096c. All six files and the full tree matched;
+core/integration/examples/SQLite/API/type/gem and four paired scenarios passed.
+R07 is complete. The published diagram is applied40-01. R08/D08 now has a Refactor
+41 candidate, with R09 and R10 remaining afterward. Their behavior and naming
+decisions are not part of Context preparation extraction.

data/docs/architecture/entry-action-and-team-wording.md

@@ -0,0 +1,72 @@
+# Entry-action names and Team task wording (R10)
+
+## Scope
+
+Refactor 44 follows applied Refactor 43, core
+`5c4c039273eb2324fcc9e9943ccf40bd1ffb3abd`. It changes two private action names
+and two Team-generated strings. No new production class, alias, state, event,
+loader rule, persistence format or public method signature is introduced.
+
+## Action names describe their local work
+
+| Existing phase | Private action | Work |
+|---|---|---|
+| `filtering_input` | `apply_prepared_input_action` | Read `phronomy_filtered_input` from the prepared config and install it on the invocation. |
+| `building_context` | `build_runtime_chat_action` | Build a Chat with the prepared projection's settings and apply its instructions, Tools and messages. |
+
+These replace `filtering_input_action` and `building_context_action` respectively.
+Their bodies, arguments, return values, exceptions and ordering are unchanged.
+Input filtering and context preparation remain with the existing preparation
+owners; these actions do not repeat that work. The first action keeps its unused
+Agent argument so the existing bound-action construction remains unchanged.
+
+Phase names, transition guards, callbacks and saved resume phases remain intact.
+A phase is an existing lifecycle boundary; an entry-action name describes the
+operation performed at that boundary. Renaming phases would require a separate
+compatibility design for observation and saved executions.
+
+## Team tasks and completion handles
+
+| Surface | Before | After |
+|---|---|---|
+| `finalize.summary` parameter description | `TaskResult summary` | `Task generation summary` |
+| Newly committed `enqueue_task` result | `TaskResult #N enqueued: ...` | `Task #N enqueued: ...` |
+
+These are observable text changes, not solely internal renames. The description
+is sent to the LLM. The enqueue response is saved in Team operation metadata and
+subsequently supplied as a Tool result. The task description supplied by the
+caller is not rewritten. Tool names, argument names, types, optionality, task IDs,
+batch ordering, queue contents and cancellation behavior are unchanged.
+`Phronomy::TaskResult` continues to mean the asynchronous completion handle.
+Team integration examples now use `Task A/B/C` for business-task descriptions.
+
+The existing operation-ID deduplication returns the stored result verbatim.
+Already committed legacy `TaskResult #...` results therefore remain unchanged
+on replay, including after restart. This change does not migrate old records,
+rewrite Journals or reformat results during readback. Reusing an operation ID
+with different arguments still fails the existing identity check.
+
+## Verification and limits
+
+The package checks the existing Agent transition and Chat contracts, durable
+Team execution, full core/integration suites, offline examples, real SQLite,
+API/SPI, types, style, gem loading and independent application. One additional
+regression verifies legacy response replay after restart, no repeated writes,
+the TaskResult return type and argument-identity rejection. It also passes on
+the applied baseline.
+
+Separate processes capture a committed finalize operation before its Agent
+settlement and resume it using the other version, in both directions. Stored
+operations remain byte-equivalent at the value level, tasks are not duplicated,
+and the expected two remaining Provider calls occur. These are stubbed Provider
+checks with an InMemory snapshot; they are not live-LLM or cross-version SQL tests.
+
+The review exposed an existing [Tool schema recording gap](tool-schema-recording-gap.md)
+on RubyLLM 1.16.0. R10 does not repair it or weaken definition checks. Successful
+continuation here does not prove that incompatible parameter definitions are
+rejected. The generated parameter description changes, while the current saved
+Tool definition omits parameter details.
+
+R09 is applied and verified. R10 is implemented and locally verified, pending
+application verification. The newly discovered schema issue remains open, so
+closing the original R/D inventory must not be described as absence of defects.

data/docs/architecture/execution-metadata-and-values.md

@@ -0,0 +1,80 @@
+# Shared execution metadata and value conversion
+
+Refactor 38 addresses the remaining R03 and R11 responsibilities against core
+`e7e6618493df03c2eb386d78a9303796e1e13cdc`. The candidate must be applied and
+verified before those items are closed. Tool restoration itself was completed
+earlier and its validation and state reconstruction remain unchanged.
+
+## Ownership
+
+Ordinary dispatch creates durable facts before sending an external operation.
+Recovery reads those same facts after an interruption. Their stored vocabulary
+therefore belongs to the execution contract, not to a recovery procedure.
+
+| Responsibility | Owner | Callers |
+|---|---|---|
+| Metadata keys/version, Tool batch capture and metadata merge | `Agent::ExecutionMetadata` in `agent/execution` | Initial/dispatch preparation, Coordinator, approval commit, recovery and MultiAgent |
+| Stable Tool invocation identity | `Agent::ToolInvocation.semantic_id` | Ordinary Tool preparation and recovery subject construction |
+| Ruby tree conversion before JSON serialization | `Values::Serializable.convert` in `common/values` | RuntimeRecordEncoder, RecoverySupport, ExecutionMetadata and dispatch preparation |
+| Recovery descriptors and outcome interpretation | `Agent::RecoverySupport` | Recovery and the existing failure reconstruction path |
+
+ExecutionMetadata is a stateless vocabulary and snapshot helper. It does not
+start an invocation, increment revisions, open a transaction or perform recovery.
+Its `with_values` preserves the old execution revision. ToolInvocation's
+`semantic_id` computes the same prefixed SHA-256 value over the same four IDs
+and NUL separators; it never constructs, authorizes or runs a Tool.
+
+RecoverySupport's shared constants and snapshot/merge/identity operations are
+removed, with all repository callers updated. No compatibility aliases are
+added for these private implementation names. `ExecutionOutcomeCommitter`
+still uses `RecoverySupport.error_from_failure` for actual failure reconstruction;
+this change does not claim to remove every execution/recovery dependency.
+
+## Conversion contract
+
+Serializable rebuilds Hash and Array containers, stringifies Hash keys and
+Symbol values, retains scalar objects, and recursively processes `to_h` results.
+It preserves input order and the previous last-value-wins behavior for keys
+that become equal. It does not deep-copy String values, freeze results, reject
+non-Hash `to_h` results, or catch exceptions raised by application conversion.
+
+The unsupported-value error remains ArgumentError. Callers supply their
+existing diagnostic prefix, including for errors inside nested values:
+
+| Boundary | Exact prefix before `: <class>` |
+|---|---|
+| RuntimeRecordEncoder.json_value | `unsupported canonical runtime value` |
+| RecoverySupport.canonical_copy and existing snapshot writers | `Recovery value is not canonically serializable` |
+
+The two existing conversion entry points remain short adapters because they
+own different error contracts. They no longer implement separate recursive
+algorithms. Snapshot writers retain their historical diagnostic despite its
+Recovery wording, to avoid a behavior change in this responsibility refactoring.
+
+Serializable does not establish canonical JSON validity. CanonicalJSON still
+owns numeric range, non-finite/negative-zero and encoding checks. Immutable.copy
+still owns copying and freezing. ProviderCallOutcome.normalize still has its
+different unsupported-value-to-String behavior. Domain codecs keep their key
+validation and collision rules. These operations are intentionally not merged.
+
+## Compatibility and verification
+
+Stored metadata keys, version 1, Tool identity bytes and serialized values are
+unchanged. Transactions, revision checks, dispatch order, Tool restoration,
+approval notifications and external-effect behavior remain with their existing
+owners. Public API, signatures, raw Storage SPI and database schema are unchanged.
+
+The conversion behavior tests run against both the applied baseline and the
+candidate, including nested unsupported values and application exceptions.
+Existing Tool batch tests follow their new owner; the stored identity fixture
+guards compatibility. Recovery, causal durability, approval/resume and
+MultiAgent tests exercise the changed callers. Full core/integration suites,
+common examples, real SQLite, API/SPI snapshots, RBS, annotations and packaged
+gem loading complete the candidate checks. Live PostgreSQL and live providers
+are not part of this candidate's execution evidence.
+
+This improves ownership and removes a duplicated recursive algorithm. The
+dependency diagram's module and file cycles remain; their disappearance is not
+the completion criterion. The applied SVG remains applied37-01 until the next
+application verification. The other initial proposal groups are R06, R07,
+R08/D08, R09 and R10; overall refactoring is not complete.