phronomy 0.26.0 → 0.27.0

data/docs/architecture/remaining-refactoring-plan.md

@@ -0,0 +1,374 @@
+# Remaining responsibility refactoring
+
+This tracks responsibility work, remaining proposals and acceptance gates; it does
+not define a new Storage SPI or Workflow lifecycle contract. The historical
+inventory baseline was core `e4ad9948798a4f165d052bd8ab5ac3574cf48e24`
+and examples `2f8b467f1268dd21de4c02b1c90c8bdd211d1feb` on `refactor/architecture`.
+
+W1 is now verified at core `42f61514929645662e16b571afff9f4060d867d1`.
+W2a is applied and verified at core `01cd2f57549f6d1e60825254f4520d0f123e651c`.
+W2b is applied and verified at core `fcd434c45ad98e5c93953cbce1ffef3c12246894`. See the
+[W2 design review](workflow-terminal-ownership-design.md) and
+[ADR-056](../decisions/056-workflow-terminal-policy-ownership.md).
+
+The current applied baseline is core
+`5c4c039273eb2324fcc9e9943ccf40bd1ffb3abd` and examples
+`68a0bbd0e354b9e00bbfed728ad2b769b389ed8a` (Refactor 43; examples unchanged).
+S2b/S2c were verified on Refactor 35, including PostgreSQL CI against its
+core ebd99623 / examples 68a0bbd0 pair.
+Refactor 36's S3, Refactor 37's D02, Refactor 38's R03/R11, Refactor 39's R06
+and Refactor 40's R07 are applied and verified, as is Refactor 41's R08/D08.
+The diagram is on applied43-01. Refactor 42 Tool binding and current DSL
+contracts and Refactor 43 Chat/state ownership are applied and verified; R09
+is closed. Refactor 44 implements R10, pending application verification. The
+new Tool schema recording finding remains open. See the
+[closure review](refactoring-closure.md) for retained names, evidence and limits.
+
+## Completed boundaries
+
+ExecutionCoordinator's staged split, ToolInvocation restoration ownership and
+SharedState's MultiAgent ownership are complete. Domain codecs/repositories
+already belong to Agent, MultiAgent and Workflow (ADR-033). Raw storage conflicts
+already use Storage-owned exceptions (ADR-043). `FSMProtocol::FINISH` already
+owns the common terminal marker; that earlier constant dependency is not the
+remaining Workflow problem.
+
+## Execution order and completion gates
+
+| Step | Remaining concern | Scope and completion gate |
+|---|---|---|
+| W1: Refactor 31 | Two terminal-save implementations, selected by prepend | Applied and verified. The active F1-aware implementation belongs to Runner and the override is removed. See [ADR-054](../decisions/054-workflow-terminal-save-single-owner.md). |
+| W2a: Refactor 32 | Terminal observer exceptions leave stream and admission pending | Keep the error path open through notification, preserve the original exception and any confirmed save, and verify application before ownership extraction. See [ADR-055](../decisions/055-terminal-observer-failure-settlement.md). Applied and verified at 01cd2f57. |
+| W2b: Workflow terminal ownership | FSMSession interprets `workflow_terminal_persistence_result` and success/known-failure/unknown outcomes | Applied and verified in Refactor 33 at fcd434c4; WorkflowTerminalPolicy and FSMProtocol::TerminalDecision own the boundary. Preserve session identity, event acceptance, stream barriers, admission retention/release and Task ordering. Do not simply hide the same Workflow policy behind renamed Engine methods. |
+| S1: Storage contract design | Eight fixed repository slots and Agent watermark are in the shared contract | Design completed: Records/Streams/Blobs with conditions and guarded checks. The existing 37 raw methods have been inventoried; S2b now implements that design. |
+| S2a: Refactor 34 | Existing update, batch validation and nested transaction differences | Applied and verified at core ac07b6d4 / examples ae538996, including PostgreSQL 17.11 on Ruby 3.2/3.3/3.4. See ADR-057. |
+| S2b: Neutral Storage SPI | Common/domain contracts and all backends must agree | Applied and verified at ebd99623 / 68a0bbd0: Records/Streams/Blobs, feature schemas/adapters, failed-view lifecycle and non-local-exit rollback. See ADR-058. |
+| S2c: Integration and migration | Physical backends must satisfy the same contract | Completed for Refactor 35. PostgreSQL 17.11 on Ruby 3.2/3.3/3.4: 119 examples per version; SQLite: 116. All 13 CI jobs checked out the verified core/examples pair. API/RBS, gem, round-trip data compatibility and applied trees were verified. |
+| S3: Naming and closure | Common framework naming and public Persistence facade can be conflated | Reviewed and implemented in Refactor 36: retain public Persistence, neutral Storage, feature schemas and separate composition; move resource-reference normalization from generic Validation to Resource. Update stale status documents. Applied and verified at d98822b3; do not rename merely to simplify a diagram. |
+
+W1 precedes W2 so the active terminal save is explicit before its session-facing
+ownership changes. W2 can be completed without redesigning Storage's raw SPI.
+Storage follows because its common contract affects all domain repositories and
+both SQL reference implementations. Verify the applied commit before producing
+the next dependent source package.
+
+## W2 implemented boundary
+
+Runner retains snapshot capture, Offload submission, one save and F1 readback.
+WorkflowTerminalPolicy recognizes the Workflow result event and interprets its
+outcomes. FSMSession receives only complete/fail/retire decisions and owns its
+pending state; Registry remains the sole Workflow admission owner.
+
+The private terminal_policy injection replaces terminal_barrier, without a
+public plugin API or alias. Agent/Tool and ephemeral Workflow keep immediate
+completion. Unknown outcomes retain admission and an unresolved caller until
+normal shutdown clears admission; shutdown does not synthesize a caller result.
+Refactor 32's observer-error ordering and committed snapshot are preserved.
+
+The candidate tests delayed success, known failures, F1 reconciliation,
+uncertainty/shutdown, early/duplicate/late events, ordinary events during the
+barrier, observer errors, rejected submission/delivery and shared Agent/Tool
+behavior. Its application verification is complete; Storage S1 design followed.
+
+## S1 baseline operation inventory (before SPI 2)
+
+Removing Agent/Workflow constant references did not make the SPI domain-neutral.
+`Storage::Backend < Storage::Repositories` constructed eight required slots;
+`assert_agent_watermark!` checks Agent revision and Journal position together.
+
+| Current area | Existing constraint to preserve | Ownership/design question |
+|---|---|---|
+| Contents | Canonical content identity and reads/writes join the same transaction | Keep the content contract without coupling it to an execution owner. |
+| Agents / Teams | Key identity and expected/next revision CAS | Separate physical compare-and-write from domain record validation. |
+| Journals | Expected head position, append order and record identity | Preserve atomic append; a generic key/value write alone is insufficient. |
+| Agent / Team executions | Atomic active-owner exclusion, immutable owner identity, revision checks and indexed queries | Decide a neutral constraint/index primitive or explicit domain-owned extension; never replace atomic admission with an unlocked preflight. |
+| Workflow / Handoff states | Create/update/delete CAS and stored identity | Preserve nil pre-revision creation and conditional deletion, with domain interpretation above the raw contract. |
+| Agent watermark | Revision and Journal head observed consistently with subsequent writes | Express a multi-record precondition or domain-owned transaction operation, not independent reads above the backend. |
+| Transaction view | All eight repositories, content and watermark share one view | Keep InMemory's one Monitor/snapshot and each SQL view's one checked-out connection; splitting classes must not split commits. |
+| Errors / capability declarations | Dedicated active constraint errors, ordinary conflicts and uncertainty remain distinct | Revisit domain terms in capabilities without adding stronger concurrency or commit-certainty promises. |
+
+Reference implementations live in `storage/backends/in_memory.rb` and examples
+`30_sqlite_persistence` / `31_postgresql_persistence`. Inspect SQL indexes, lock
+order, connection binding and rollback as well as Ruby signatures. Storage's
+existing Agent/Team implementations have different details; do not assume they
+are interchangeable just because their method names resemble each other.
+
+S1 must produce a mapping from every current operation to its owner and atomic
+primitive, plus API/RBS migration and backend conformance gates. Do not adopt a
+generic key/value API, callbacks inside transactions or a registry of arbitrary
+operations merely to erase domain names. Keep record type/version/payload,
+existing F0/F1/F4 limits and the X0 external-effect boundary explicit.
+
+See the existing [persistence staged plan](persistence-refactoring-plan.md),
+[ADR-033](../decisions/033-domain-persistence-ownership.md) and
+[ADR-043](../decisions/043-storage-execution-constraint-notifications.md).
+
+## S2a and S2b applied boundaries
+
+[ADR-057](../decisions/057-storage-transaction-boundaries.md) records the three
+behavioral changes. The [migration guide](../migrations/storage-transaction-boundaries.md)
+explains nested savepoints and propagated ActiveRecord::Rollback. Complete batch
+validation prevents invalid input from leaving partial Journal rows; it does not
+make arbitrary database failures safe to catch inside the failed scope.
+
+S2a alone did not complete Storage. Refactor 35 subsequently implemented the
+neutral SPI, failed-view rules and non-local exits, then passed live PostgreSQL
+acceptance against the applied core/examples pair. Reference SQL code parity
+alone was not used as PostgreSQL execution evidence.
+
+## Refactor 35 verification history
+
+Core baseline: ac07b6d4b47167ae404c8ecad8450e80a0087754.
+Examples baseline: ae538996fd276faa3dac0990839e9cf115e6dff6.
+S2b changes the raw SPI and both SQL implementations together. Domain APIs and
+stored formats remain. Candidate checks include InMemory, real SQLite, generic
+resource declarations, scope failures and old/new/old SQLite data compatibility.
+The applied pair above passed all three examples workflows, including
+[PostgreSQL](https://github.com/Raizo-TCS/phronomy-examples/actions/runs/35827495677),
+[SQLite](https://github.com/Raizo-TCS/phronomy-examples/actions/runs/35827495667) and
+[current API](https://github.com/Raizo-TCS/phronomy-examples/actions/runs/35827495646).
+Each job's checkout SHA was verified, not just its green status. Core remote
+workflows had no runs; local core suites supplied that evidence.
+
+## Closure boundary
+
+W1, W2a, W2b, S1, S2a, S2b and S2c are applied and verified. S3's bounded Storage
+cleanup and audit are applied and verified in Refactor 36.
+The original review is not fully implemented: the W/S-only inventory omitted
+D02, R03's metadata boundary, R06, R07, R08/D08, parts of R09, R10 and R11.
+See the reconciled inventory below; do not count those proposals as completed.
+Keep the published dependency SVG tied to applied41-01 until Refactor 42 application verification. Performance benchmarking, live-LLM behavior,
+distributed ownership and unknown-outcome recovery policy are separate scopes,
+not silently added requirements for this responsibility refactoring.
+
+## Initial review proposals and current disposition
+
+| Initial item | Current assessment and follow-up |
+|---|---|
+| D02 | Applied and verified in Refactor 37: callers construct OperationBinding directly and retain ordering and cancellation contracts. |
+| R03 | Applied and verified in Refactor 38: ExecutionMetadata owns shared durable keys and snapshots; ToolInvocation owns stable identity. Earlier restoration behavior is preserved. |
+| R06 | Applied and verified in Refactor 39: InvocationTransitions owns Tool events, ordered external transitions and state declarations for both builders and Invocation. |
+| R07 | Applied and verified in Refactor 40: ContextAssembler describes preparation through private instruction, record-candidate, candidate-merge and current-input operations. |
+| R08 / D08 | Applied and verified in Refactor 41, one overlapping item: GeneratorVerifier keeps its facade and Result; private WorkflowBuilder, AgentResultReceiver and the moved PipelineState separate graph construction, reception and state. |
+| R09 | Applied and verified in Refactors 42 and 43: Tool binding, declaration rules, Chat construction and explicit state ownership. Existing DSL behavior is retained. |
+| R10 | Implemented in Refactor 44: private actions describe prepared-input installation and runtime Chat construction; Team-generated text describes business tasks. Application verification is pending. |
+| R11 | Applied and verified in Refactor 38: Values::Serializable owns recursive conversion. Caller-specific diagnostics and distinct immutable/canonical/codec contracts remain. |
+
+R08/D08 is one work item. R03's Tool restoration and shared metadata ownership
+are complete; do not reopen those contracts. R09's configuration inheritance can
+change public behavior and needs its own explicit decision. These are existing
+proposals rediscovered by the S3 audit, not new performance or distributed-runtime
+requirements. D02, R03/R11, R06, R07 and R08/D08 are applied and verified.
+Refactor 43 application is verified and R09 is closed. Refactor 44 implements
+R10; verify its application before closure. Track the new Tool schema finding
+separately from the original R/D inventory.
+
+
+## D02: direct operation binding (Refactor 37, applied)
+
+OperationBinding already owns invocation context validation, its private linked
+cancellation token, deadline subscriptions and result-scoped cleanup. Its three
+clients now construct it directly. Execution's pass-through factory has no
+additional behavior and is removed without an alias or replacement factory.
+
+Construction remains at the same points: Agent before command admission,
+Blocking only with an explicit context and before Offload submission, and
+Orchestrator for each child before invoke_async. Keep bind/track/close ordering,
+error handling, context selection and cancellation ownership unchanged.
+Orchestrator still uses Execution for fan-out/fan-in; that dependency is intended.
+The internal OperationBinding signature and body, except its ownership comment,
+are unchanged. No class, production file, public API or examples change is added.
+
+The distribution is applied and verified at e7e66184. D02 is closed.
+Seven initial-proposal groups remained at that point; R03/R11 are now applied below.
+
+
+## R03/R11: shared execution metadata and conversion (Refactor 38, applied)
+
+See [the ownership and compatibility design](execution-metadata-and-values.md).
+ExecutionMetadata owns the shared keys, version, snapshot and merge.
+ToolInvocation.semantic_id owns the stable Tool identity, while
+Values::Serializable owns recursive Ruby-to-JSON-tree conversion.
+RecoverySupport retains recovery interpretation; the existing conversion entry
+points retain their distinct diagnostics. No new restoration, transaction or
+external-operation behavior is introduced.
+
+Refactor 38 is applied and independently verified at core 690b2823, tree
+67ea6df833254341043c3fb1e99729d66f9598f6. All 30 full files and the tree match.
+Core 2,970 (61 pending), integration 367 (28 pending), common examples 42 and
+SQLite 116 passed with zero failures, as did API/RBS, style and gem checks.
+R03/R11 are closed. Five groups remained at that point; R06 is now applied below.
+The diagram was synchronized to applied38-01 then and is now applied42-01.
+
+
+## R06: Agent transition ownership (Refactor 39, applied)
+
+See [the transition ownership design](agent-transition-ownership.md).
+InvocationTransitions owns the six Tool event names, thirteen external event
+families and their ordered transitions, initial phase and state classifications.
+PhaseMachineBuilder compiles the external transitions into state_machines;
+AgentInvocationSessionBuilder passes the same definition to FSMSession.
+AgentInvocation uses the Tool vocabulary to identify payloads it handles.
+
+FSMSession still uses only source-state declarations to decide whether an
+external event is accepted or a phase must wait. The machine evaluates guards
+against the current context, after payload application. Engine does not acquire
+Agent policy, and automatic transitions and entry actions keep their owners.
+No new generic DSL, compatibility alias, public API or persistence format is added.
+R10's entry-action names and R09's DSL inheritance semantics are separate work.
+
+The implementation preserves callback-failure, Handoff-failure, Handoff-request,
+Tool-request and output-fallback priority, nil-context fallback, guard exceptions,
+approval suspension and resume. Independent behavioral expectations pass on both
+baseline and candidate; full-suite results are in the distribution evidence.
+Refactor 39 is applied and independently verified at core 4d57614a, tree
+654241da4b2b7f32d988602d28127bc1fa155641. All 10 full files and the tree match.
+Core 2,993 (61 pending), integration 367 (28 pending), common examples 42 and
+SQLite 116 passed with zero failures, as did API/RBS, style and gem checks.
+R06 is closed. Four groups remained then; R07 is now applied below.
+The diagram was synchronized to applied39-01 then and is now applied42-01.
+
+
+## R07: Context preparation steps (Refactor 40, applied)
+
+See [the preparation design and compatibility boundaries](context-preparation-steps.md).
+ContextAssembler retains its public preparation/finalization boundary and its
+existing collaborators. Seven private operations separate initial/base/Handoff
+instructions, retained instructions, record candidates, Hook/Handoff merging
+and the current-input item. No production class or file is added.
+
+The public prepare methods now describe the preparation steps; item IDs,
+provenance and metadata live in the corresponding item-building operation.
+Initial and follow-up paths share generation filtering and candidate merging,
+while preserving their distinct instruction sources, exclusion rules, call
+sequence and ask/complete delivery. Evaluation and content-store effects retain
+their order. Application Policy remains outside the caller's commit transaction;
+finalize remains validation and persistence, without a Policy call.
+
+Ten additional contract examples pass against both Refactor 39 and the candidate.
+Four paired initial/follow-up scenarios compare complete Policy input, Prepared,
+Manifest references/bytes and content operations across separate processes.
+Full core/integration/examples/API/type/package gates are in the distribution.
+
+Refactor 40 is applied and independently verified at core b3dfbc5a, tree
+dcd9d1bf8efb1b488f9c2b3b1c4e99bdeda6096c. All six files and the tree match.
+Core 3,003 (61 pending), integration 367 (28 pending), common examples 42 and
+SQLite 116 passed with zero failures, as did API/RBS, style, gem and four paired
+preparation scenarios. R07 is closed. Three groups remained at that point; R08/D08 is now applied below.
+The published diagram is applied42-01; keep it until Refactor 43 application checks.
+
+
+## R08/D08: GeneratorVerifier ownership (Refactor 41, applied)
+
+See [the ownership and event-contract design](generator-verifier-ownership.md).
+The public facade retains configuration, lazy Workflow caching, default parsers
+and Result construction. Private WorkflowBuilder owns graph assembly, request
+startup and convergence. Private AgentResultReceiver converts Agent terminal
+events into correlated Workflow events. PipelineState moves without changing its
+canonical name, fields, correlation checks or mutation behavior.
+
+The three implementation files live below generation/generator_verifier. No
+loader change or alias is needed. This updates the original D08 location sketch:
+the pattern already has generation ownership, so it does not move to MultiAgent.
+Draft/review payload meanings remain separate. Only their identical terminal
+classification, completion-notification rescue and failure notification are shared.
+The receiver holds no request-specific mutable state and never mutates Workflow
+context; PipelineState still applies accepted results on the EventLoop.
+
+Thirty-nine additional event-contract examples pass on both baseline and candidate,
+including inline completion, failures, parser/notification exceptions, old and
+duplicate results, normalization, convergence, caching and config forwarding.
+The public signature/Result/state contract also matches. Full gates are recorded
+in the distribution. Existing semantics remain: final trust is score-based, even
+if an unapproved high-score draft is finalized at the iteration limit.
+
+Refactor 41 is applied and independently verified at core e87eb77f, tree
+14dc8a546a4fd96e19e0713f7480ca2efa3c331a. All nine files and the full tree match.
+Core 3,042 (61 pending), integration 367 (28 pending), common examples 42 and
+SQLite 116 passed with zero failures, as did API/RBS, style, gem and explicit
+public/Result/state comparisons. R08/D08 is closed; R09 and R10 remain.
+The diagram is applied41-01.
+
+
+## R09: Tool binding and declaration rules (Refactor 42, applied)
+
+See [the boundary design and inheritance matrix](agent-configuration-and-tool-binding.md).
+Base retains its preparation hook, non-Class passthrough and setting selection.
+Agent::ToolBinding creates alias/filter decorators and forwards custom async
+logical/physical completion. The default async path stays inherited to avoid
+applying filters twice. ToolInvocation and Orchestrator retain their owners.
+No Agent reference or private callback into Base is passed to ToolBinding.
+
+Thirty-five new examples pass on both baseline and candidate. Current DSL rules
+are explicit, including non-inherited model/budgets/filters, live parent lookups,
+shared instructions/policy/Tool-list values and inherited aliases that nil does
+not remove. This package does not unify public configuration behavior.
+
+Refactor 42 is applied and verified at core 4a57a3c2, tree
+1a43ec3fecd5457e4314afa3807eb862bbd16b52. All nine files and the tree match.
+Core 3,077 (61 pending), integration 367 (28 pending), examples 42, SQLite 116
+and the packaged persistence contract 41 pass with zero failures. Public
+contracts, API/SPI, types, style and gem loading also pass. This closes the
+first slice; the original R09 Chat/state scope is addressed below.
+
+## R09: Chat construction and explicit state ownership (Refactor 43, applied)
+
+See [the Chat/state ownership design](agent-chat-and-state-ownership.md).
+RuntimeChatBuilder owns provider Chat creation, settings and cached instructions.
+StateWriter owns initial root/context/knowledge writes and explicit idle-Agent
+mutations, using the captured root and one transaction. Both live in the existing
+context_assembly directory. They hold no Agent reference or private callbacks.
+
+Base keeps the facade, live-owner checks, root proposals and publication. Its
+projection hook preserves instruction/Tool/message order and existing overrides.
+The writer returns root and records only after the transaction returns; Base
+publishes Journal records before replacing the live root. Initial input order,
+idle checks, CAS, revisions, exception identity and rollback behavior are retained.
+Unknown commits, local publication failure and application-owned outer
+transactions retain their existing limitations; no new reconciliation is added.
+
+Thirty-seven new behavioral examples pass against both Refactor 42 and the
+candidate. Full core/integration/examples/SQLite and API/SPI/type/style/package
+gates are recorded in the distribution. Static dependency analysis preserves
+all existing cycle memberships, with one new context_assembly -> lifecycle pair.
+This improves responsibility boundaries; it does not remove existing cycles.
+
+Refactor 43 is applied and verified at 5c4c0392, tree
+841bc7b5b28c2d31380ee4a12ffdc22a85ee3c37. All ten files and the full tree match.
+Core 3,114 (61 pending), integration 367 (28 pending), examples 42, SQLite 116
+and gem contract 41 pass with zero failures. R09 is closed; SVG is applied43-01.
+No live-LLM, live PostgreSQL, remote-CI success or performance claim follows
+from that local validation.
+
+
+## R10: Entry actions and Team wording (Refactor 44 candidate)
+
+See [the naming and compatibility boundary](entry-action-and-team-wording.md).
+Only two private action names and two generated Team strings change in production.
+State/event vocabulary and action bodies stay unchanged. Legacy saved operation
+results are returned as stored; new operations use business-task wording.
+The original R/D inventory has no other unimplemented item, but R10 remains
+pending application verification.
+
+## New open finding: Tool parameter schema recording
+
+The [Tool schema recording gap](tool-schema-recording-gap.md) was reproduced on
+Refactor 43 and Refactor 44 with RubyLLM 1.16.0. The actual schema reader is
+`params_schema`, whereas ToolDefinitionSet records `{}` when its expected
+`parameters_schema` reader is absent. A required/type change can evade the saved
+comparison. This is the next correctness issue to design, with explicit handling
+of historical manifests. It is not fixed by R10 or by passing its recovery tests.
+
+## Refactor 44 applied; Refactor 45 migration candidate
+
+R10 was applied at 99ee43cd7b48174d825d20876fc38bbe47e6da11, tree
+34de332df150ff28ac93b2d04e099197f4a214d1, and verified. The original R/D inventory
+is closed. Earlier candidate wording above is historical.
+
+RubyLLM 2.0.0 now supplies the awaited provider-neutral output cap.
+[Refactor 45](rubyllm-2-token-ownership.md) implements the dependency/API migration,
+input-only registry budgeting, output-cap forwarding, schema recording/comparison
+and coordinated examples migration. The schema issue is addressed in this candidate;
+old empty-schema manifests require completion on the original version before upgrade.
+Local verification and the exact package trees are recorded in the distribution.
+User application verification remains outstanding; this is not a published release.

data/docs/architecture/rubyllm-2-token-ownership.md

@@ -0,0 +1,82 @@
+# RubyLLM 2.0 and token ownership (Refactor 45)
+
+This candidate targets RubyLLM 2.0.x (`~> 2.0.0`), verified with 2.0.0.
+It implements the previously deferred token-ownership plan against the current
+0.26.0 refactoring branch. It does not publish or renumber the Phronomy gem.
+
+## Ownership
+
+| Concern | Owner and behavior |
+|---|---|
+| Input capability | RubyLLM model registry `context_window`, defined by RubyLLM 2 as maximum input tokens |
+| Model lookup | `RubyLLM.models.find(model, provider: provider)` |
+| Input budget | Phronomy `TokenBudget(max_input_tokens:)`, using that limit directly |
+| Unknown/invalid input limit | No hard token budget; no invented limit or reserve |
+| Requested output cap | Agent `max_output_tokens`, positive Integer; stored in model_config |
+| Output request rendering | RubyLLM `Chat#with_max_output_tokens`; all wire names remain upstream |
+| Context selection | Phronomy ContextPolicy and final Manifest validation |
+| Replay | Recorded Manifest segments and request intent; no current-budget reselection |
+
+Remove application calls to `Agent.context_window` and
+`configuration.default_output_reserve`. They no longer exist.
+`before_llm_input` patches containing `context_window` raise ConfigurationError;
+register custom/local model metadata through RubyLLM's public registry loader.
+`max_output_tokens` does not reduce the input budget and is not inferred from
+registry output capacity. Omit it to use RubyLLM/provider defaults.
+The obsolete InvalidContextBudgetConfigurationError has also been removed.
+New manifests have assembly policy version 9. Historical model_config keys are
+not rewritten during materialization, and the runtime builder forwards only
+supported request settings.
+
+## RubyLLM 2 compatibility
+
+The adapter uses `with_tools`, keyword Tool execution, `parameters_schema`,
+`provider_options`, `Message#model`, and `Tokens#cache_read/#cache_write`.
+Phronomy's `param`, `params`, `with_params`, `params_schema`, and `provider_params`
+remain available as its own Tool contract. RubyLLM 2's derived class tool name
+is used when no explicit name is supplied. Structured historical content is
+encoded as JSON text when materialized into RubyLLM 2 Messages. Stored canonical
+content is unchanged. Phronomy TokenUsage retains its cached/cache_creation names;
+recovery reads both the historical and new RubyLLM counter keys.
+
+Cached instructions use `with_instructions(..., cache_until_here:)`.
+No RubyLLM 1.x guard, monkeypatch, or provider-specific output mapping remains.
+Applications choose protocol settings in RubyLLM. Its OpenAI default is Responses;
+local Chat Completions endpoints must configure `openai_protocol = :chat_completions`.
+
+Tool batches are intercepted through `after_message`, after RubyLLM has appended
+the complete assistant Message and before RubyLLM's approval/Tool execution loop.
+Phronomy's existing authorization, suspension and batch execution paths therefore
+remain authoritative. Tool classes and their approval declarations are not
+rewritten to bypass RubyLLM's gate.
+
+## Saved Tool definitions and deployment
+
+The previous empty-schema fallback concealed argument changes. New definitions
+record the actual schema and provider options and compare them canonically.
+Changes to argument type, requiredness, enum or provider options are rejected.
+
+An old `{}` schema cannot establish which parameters were originally authorized.
+The migration fails closed with an explicit diagnostic when such a saved
+Manifest is materialized; it does not synthesize or weaken historical definitions.
+Before updating, finish outstanding Agent, Workflow and Team operations that may
+need old Tool-bearing manifests on the old core/RubyLLM combination, and retain
+backups of durable storage. Do not perform a rolling upgrade with mixed versions
+sharing those in-flight executions. Completed history is not rewritten; starting
+a new invocation creates a current schema-bearing manifest. This is a deployment
+boundary, not an automatic historical-data repair.
+
+## Examples and verification
+
+The shared examples configuration registers explicit PHRONOMY_CONTEXT_WINDOW or
+observed local metadata via `RubyLLM.models.load_from_json`, retaining other model
+entries. An unavailable local limit remains nil, including when the local server
+uses a cloud model's name. Code-review chunking requires known metadata explicitly.
+Request output caps are independent constants. Rails examples use the same setup.
+
+Tests cover provider-qualified input budgets, missing metadata, output forwarding,
+forbidden hook overrides, saved intent without reselection, actual Tool schema
+comparison, old/new usage counters, Responses Tool/approval/streaming execution,
+and existing Chat Completions and durability behavior. Protocol rendering remains
+RubyLLM's responsibility. Distribution evidence distinguishes HTTP stubs and local
+SQLite from live providers, PostgreSQL and the remote Ruby-version CI matrix.

data/docs/architecture/tool-schema-recording-gap.md

@@ -0,0 +1,50 @@
+# Historical finding: Tool parameter schema is absent from saved definitions
+
+## Observed mismatch
+
+During Refactor 44 verification, Ruby 3.3.6 with RubyLLM 1.16.0 reproduced the
+following on both applied Refactor 43 and the Refactor 44 candidate:
+
+1. The prepared Tool exposes its actual argument schema through `params_schema`.
+2. `Agent::ToolDefinitionSet.build` asks for `parameters_schema`, which this Tool
+   does not respond to, and stores an empty Hash for that field.
+3. `select_definitions` compares the stored definitions exactly, but a change
+   from optional string `summary` to required integer `summary` is accepted
+   because neither definition contains its actual argument schema.
+
+The LLM request still includes the actual schema. The missing information is in
+Phronomy's recorded definition and therefore in the comparison boundary. Tool
+names and top-level descriptions are still compared; this finding does not mean
+all Tool identity checks are absent. The source of ToolDefinitionSet is unchanged
+by R10, and no claim is made about untested RubyLLM versions.
+
+## Consequence
+
+Recovery/context materialization cannot reject that incompatible argument change
+through the saved definition comparison. The R10 parameter-description change
+also does not cause a mismatch on this tested version. Passing old/new recovery
+checks must not be presented as evidence that parameter compatibility is guarded.
+
+## Required follow-up
+
+This is an open correctness issue, separate from the R10 naming cleanup.
+A follow-up should obtain the schema actually used by the supported adapter,
+record it in canonical form and compare it during context selection/recovery.
+It must also specify how to treat old saved definitions whose schema is `{}`.
+Blindly switching the reader would make new definitions conflict with historical
+manifests; blindly ignoring mismatches would erase the intended guard.
+
+Acceptance requires meaningful parameter-change rejection, matching-schema
+continuation, explicit treatment of missing historical schema, adapter-version
+coverage and old/new recovery validation. Until that work is accepted, retain
+this issue in the current work list. Refactor 44 does not silently migrate records
+or change the general Tool comparison contract.
+
+## Refactor 45 resolution candidate
+
+[The RubyLLM 2 migration](rubyllm-2-token-ownership.md) removes the empty fallback,
+records the actual schema/provider options and rejects incompatible definitions.
+It explicitly rejects historical empty schemas when materializing in-flight
+manifests. Matching current definitions continue normally. The original observation
+above is retained as evidence; it is not a description of the new implementation.
+Application verification of Refactor 45 remains pending.

data/docs/architecture/tracing.md

@@ -100,7 +100,7 @@ span.
 
 ### `multi_agent.turn`
 
-One coarse `MultiAgent::Runner` user turn. Handoff does not create a mandatory
+One coarse `MultiAgent::HandoffRunner` user turn. Handoff does not create a mandatory
 long-lived span type.
 
 ## 6. Correlation and identity

data/docs/architecture/workflow-terminal-ownership-design.md

@@ -0,0 +1,104 @@
+# Workflow terminal ownership: design and validation
+
+Implementation baseline: core `01cd2f57549f6d1e60825254f4520d0f123e651c`
+(Refactor 32 applied) and examples `2f8b467f1268dd21de4c02b1c90c8bdd211d1feb`,
+2026-09-23. W2a and W2b are applied and verified; W2b is core
+`fcd434c45ad98e5c93953cbce1ffef3c12246894` (Refactor 33). The adopted private contract is
+[ADR-056](../decisions/056-workflow-terminal-policy-ownership.md).
+
+## Role and consumers
+
+FSMSession drives one live state machine on EventLoop. WorkflowRunner assembles
+Workflow transitions, stream observation and any durable terminal save.
+AgentInvocationSessionBuilder uses the same engine for input, LLM and Tool
+progression; ToolInvocationSessionBuilder uses it for authorization, approval
+and Tool execution. Therefore the session stays in Engine.
+
+The former leak was narrower: Engine recognized the Workflow persistence event
+and interpreted its save outcomes. WorkflowTerminalPolicy now owns that rule.
+
+## Ownership and concrete boundary
+
+| Owner | Responsibility |
+|---|---|
+| FSMSession | Identity/sink, transitions, live context, pending terminal kind/notification flag, event acceptance and final notification/event ordering. |
+| WorkflowTerminalPolicy | Start the injected save callback; recognize the Workflow result event; map its outcome to a generic terminal decision. |
+| FSMProtocol::TerminalDecision | Immutable `action` and `error` value shared by a domain policy and the session. No live session authority. |
+| WorkflowRunner | Construct a policy for durable execution; retain snapshot capture, one save, F1 readback and caller completion. |
+| WorkflowExecutionRegistry | Admission, owner tokens, session routing binding and recovery-required ownership. |
+| EventLoop | Event routing, management events, retirement, source completion and shutdown. |
+
+Runner builds a policy only when both repository and persist are enabled.
+Agent, Tool and ephemeral Workflow need no dummy policy or delayed completion.
+The policy retains only its persistence callback, with no lifecycle flags.
+
+The three private operations are `start(terminal_type:, context:, event_sink:)`,
+`handles?(event)` and `decision_for(event)`. Start does not return completion
+permission. The decision value maps Workflow success to `complete`, known
+failure to `fail`, and unresolved uncertainty to `retire`. Failure preserves the
+original exception or the existing missing-error fallback. Invalid outcomes
+remain errors. Engine no longer branches on Workflow's event or outcome values.
+
+FSMSession alone tracks `running`, `awaiting_terminal`, and its final lifecycle
+state. Matching early events are discarded before invoking decision_for;
+ordinary events cannot advance while awaiting; events after done are ignored.
+The retirement action reuses the existing recovery-required management route.
+
+## Preserved durable ordering
+
+1. Session reaches a logical wait/completion boundary and captures metadata.
+2. Session marks itself awaiting a decision before invoking the policy.
+3. Runner marks admission persisting_terminal and captures an immutable command.
+4. Offload saves once and reconciles an uncertain result when possible.
+5. The bound EventSink returns the result to that session on EventLoop.
+6. The policy interprets the result only while the session accepts it.
+7. A complete decision permits the deferred observer, then the terminal event.
+8. EventLoop retires the session; Runner releases admission before settling the caller.
+
+An observer exception still uses Refactor 32's ordinary error path, with the
+already confirmed snapshot retained. No observer retry or extra save is added.
+
+Unresolved uncertainty instead retires the session and retains recovery-required
+admission without falsely settling the caller. Normal shutdown clears that
+ownership and ends the dispatcher, while the caller remains pending; unexpected
+dispatcher failure retains its separate existing waiter-cleanup behavior. This
+change does not promise that normal shutdown resolves an unknown commit.
+
+## Alternatives and compatibility
+
+Moving the full session would introduce Workflow dependencies into Agent/Tool.
+Renaming event strings in Engine would leave semantic ownership unchanged.
+Subclass/prepend overrides would recreate the hidden execution path removed by
+W1. Saving after retirement or settling on a worker would break the barrier.
+The injected policy keeps each rule at its existing execution authority.
+
+The internal constructor changes from terminal_barrier to terminal_policy;
+there is no compatibility alias or new public plugin API. Without a policy,
+Engine does not reserve a Workflow-specific event name. Production Workflow
+emits the result event only when it has injected its durable policy.
+Public signatures, Workflow command/result identities, data records and Storage
+SPI stay unchanged. One policy class and one decision value type are added;
+this is responsibility separation, not a total-line-count reduction.
+
+## Acceptance evidence
+
+| Scenario | Test boundary |
+|---|---|
+| Immediate completion/halt and Agent/Tool | Existing Workflow/Agent/Tool suites and generic no-policy completion. |
+| Delayed save and halted stream | Real Runtime admission tests prove no early result/notification. |
+| Portable failures and F1 post/pre/conflict/unreadable | Existing save tests plus real Runtime pre-state and uncertainty tests. |
+| Unknown result and normal shutdown | Admission retained until shutdown, session unbound, caller remains pending. |
+| Early/ordinary/duplicate decisions | Non-Workflow policy/session contract and Workflow policy wiring tests. |
+| Late sink and new incarnation | Real Runtime rejects an old sink for the same logical Workflow ID. |
+| Terminal observer failure | Refactor 32's four public stream regressions. |
+| Submission rejection and delivery rejection | Existing error path releases admission; rejected delivery logs without retry. |
+| Invalid outcomes and missing error | Workflow policy through the real Runner/session assembly. |
+| Load, types, API, gem and source boundary | Full validation and private ownership regression assertions. |
+
+The pre-state, uncertainty/shutdown, stale-sink and rejected-delivery scenarios
+also pass on the Refactor 32 baseline; they characterize preserved behavior.
+New protocol tests establish the extracted ownership contract. Refactor 33
+application verification completed W2b. Storage S1/S2 followed and passed on
+Refactor 35; see the [closure review](refactoring-closure.md) for S3 and the
+current applied/candidate boundary. The earlier Refactor 32 baseline remains
+historical evidence for preserved behavior.