phronomy 0.27.0 → 0.29.0

data/docs/architecture/error-api-review.md

@@ -0,0 +1,245 @@
+# Error API review (DX05-A / EA01–EA06)
+
+Applications should branch on the meaning of a failed public operation without
+knowing its backend or reconstructing it from an error message. The review uses
+core `5b9d1047cc1351a935a7871ae7705c65166ea971` and examples
+`5f4d58dc9432a84cb4421d3cc7dc2da92aee3c72` as its baseline.
+
+The original DX05-A change implements the error API part of the follow-up design. DX05-B
+(notification wiring), C (review result collection), D (`task_state`) and E
+(Agent scope/unload) remain separate work. Their proposed APIs are not provided
+by this patch. EA06's integration with D/E cannot be accepted before those APIs
+exist. Live PostgreSQL, Redis, provider services and complete Rails execution
+are separate acceptance gates; see the delivery's verification record.
+
+The subsequent, unreleased DX05-D change now provides `task_state`; see
+[its design and acceptance boundary](dx05-workflow-task-state.md).
+Its error decision is included below. Agent scope/unload (DX05-E) remains
+separate work. This does not change the historical DX05-A baseline above.
+
+## Rules and ownership
+
+* The owning Contract defines the failure category. A class is added only when
+  a caller has a distinct, stable decision to make. Detailed reasons use an
+  optional String `code`; they do not imply retry safety, rollback or worker exit.
+* H00 owns the base Error and generic diagnostic projection/reconstruction.
+  It does not identify Agents, choose a retry policy or interpret domain codes.
+* C07 Persistence and C12 Storage retain independent error hierarchies.
+  StorageBoundary translates only its existing known categories with an explicit
+  cause. A storage reason is not automatically a persistence reason.
+* C13 transports the exception. It does not classify Agent, Team or Workflow
+  failures. `:cancelled` and a failed task carrying CancellationError remain
+  different facts. Partial `outcomes` remain on their existing execution errors.
+* ArgumentError/TypeError describe Ruby/API input or mapping errors where already
+  documented. NotImplementedError marks an abstract extension point; it is not
+  converted into a provider failure.
+* Existing message-only constructors remain valid. Seven public specialized
+  constructors now accept optional `code:` without changing their attributes.
+  New target-absence/busy constructors own fixed codes and object identities.
+* Sync/async operation failures keep their category, reason and original cause.
+  Existing entry-time validation and submission rejection may still raise before
+  a TaskResult is returned. A TaskResult is not a promise of rollback.
+
+## Operation decisions and acceptance
+
+Each row names the operation family reviewed, its observed channel, the retained
+asymmetry and the action. This is an evaluation of these operations, not a claim
+that every possible backend failure has been injected.
+
+| Owner | Public operations / failure meaning / channel | Decision and application effect | Acceptance evidence |
+|---|---|---|---|
+| C01 | TeamCoordinator.create/load: root absence, duplicate identity, uncertain create; direct raise | Add TeamNotFoundError only around the requested root load. Duplicate create retains Persistence conflict: a separate AlreadyExists class adds no necessary recovery choice here. A failed create readback keeps the original failure. | team_coordinator_spec; durable_coordination_spec |
+| C01 | invoke/admission, TeamExecutionRepository.create_active/save/assert_idle!: active Team run | TeamBusyError with team_id and team.busy replaces AgentBusyError only for Team ownership. Child-Agent failures retain their own classes. No AgentBusy alias or inheritance. | execution_constraint_translation_spec; shared SQL coordination contract |
+| C01 | HandoffRunner.invoke/cancel, Orchestrator fan-out, operation rejection | Retain ConfigurationError, HandoffError, StateConflictError, recovery requirements and on_error policy. Missing retained children are not missing Teams. Readback reconciliation may itself fail and does not prove absence. OperationRejected stays private; public code team.enqueue_after_finalize is unchanged. | durable_coordination_spec; integration/team_coordinator_spec; SQL reason diagnostics |
+| C02 | Workflow definition/action, WorkflowContext writes, state CAS, waiting/resume | Retain ConfigurationError, WorkflowContextOwnershipError, WorkflowAsyncActionError and persistence conflict. Workflow has no equivalent target-root load API to justify another NotFound class. DX05-D adds WorkflowTaskResumeError with workflow.task_resume_unsupported only for unsupported restoration of a task-state phase, before any start side effect. Start/source/apply failures keep their original errors, and task cancellation remains distinct from a failed CancellationError. Agent scope is separate. | workflow and execution unit/integration suites; task_state_spec; shared SQL task-state contract (live PostgreSQL acceptance pending) |
+| C03 | GeneratorVerifier.invoke; parse fallback and confidence decision | Preserve ParseError-only fallback and LowConfidenceError.result. Add optional constructor code; do not absorb provider/callback errors into a GenerationError. | generator_verifier specs; error_api_diagnostics_spec |
+| C04 | Base.load, create/get, invoke/resume/purge | Add AgentNotFoundError only at the requested root. Journal/content/execution absence remains persistence failure. Preserve foreign AgentNotFound identity. AlreadyExists/Busy/Purged, uncertain purge and recovery-required retain their meaning. | error_api_boundaries_spec; Agent lifecycle/recovery suites |
+| C04 | stream listener policy; result/failure persistence | StreamCallbackError keeps event_type/original_error/result, with optional code. Listener :fail_task versus :log_and_continue remains explicit; no unconditional callback swallowing. | stream_callback_error_policy_spec; error_api_diagnostics_spec |
+| C05 | Assembly.prepare and policy invocation; plan/budget validation | Keep BudgetExceededError and ManifestError. Reuse C15 public trace_with, metadata only; a finish failure cannot mask policy failure or export the returned context. | error_api_boundaries_spec; Context suites |
+| C06 | Tool.call / native async operation; schema, execution, async handle validity | Keep ToolError class; supply tool.invalid_arguments / tool.execution_failed / tool.invalid_async_result at owned conversion sites. Explicit async cause fixes delayed-failure information loss. Existing ToolError/cancellation pass through unchanged. :suppress survives logger failure. | tool/async_operation_spec; tool/base_spec; schema_error_spec |
+| C07 | StorageBoundary, transaction, SaveOutcome, SnapshotComparison | Retain known-category mapping and original cause. Unknown I/O/application failures pass through. Keep committed/not_committed/unknown separately from exception class; no code-based reconciliation. | storage_boundary_spec; failure_contract_spec; snapshot_comparison_spec; SQL suites |
+| C08 | fetch, fetch_text, fetch_json and content identity | Invalid requested JSON is IntegrityError with content.invalid_json and original ParserError; invalid UTF-8 is content.invalid_encoding. Raw fetch failures pass through; no dependency on OutputParser. Requesting JSON for plain text is also invalid representation, not proof of physical corruption. | error_api_boundaries_spec; content conformance; SQLite |
+| C09 | LLM complete/stream, request/result checks, RubyLLM conversion | Keep Authentication/RateLimit/ContextLength as TransportError children and InvalidResult separate. Unknown exceptions, cancellation and callbacks retain identity. Existing SDK conversion is not an automatic retry policy. | LLMAdapter unit/integration suites |
+| C10 | VectorStore add/search/remove/clear/size and AsyncClient | Keep InvalidResultError for invalid response and driver communication errors unchanged. Driver-specific transaction/effect uncertainty is not normalized without a backend-specific contract. No universal VectorStore TransportError or sibling-contract borrowing. | VectorStore and async-client suites; live PG/Redis pending |
+| C11 | Embeddings.embed / AsyncClient; RubyLLM errors | Add owner-local AuthenticationError and RateLimitError under existing TransportError. Callers can request credentials versus surface quota refusal. Other SDK errors retain TransportError; arbitrary I/O failures, cancellation and programming errors are not guessed to be SDK failures. | error_api_boundaries_spec; embeddings/async_client_spec; RubyLLMEmbeddings specs |
+| C12 | Records.read/fetch, conditions/unique constraints, streams/blobs, atomic views | Keep nil read versus raising fetch; preserve condition/resource/constraint. Add optional code to specialized constructors; SPI 2 and storage format unchanged. No Agent or Persistence semantics in the backend. | storage SPI snapshot; backend conformance; SQLite |
+| C13 | TaskResult completion, map/flat_map/all_settled, wait/timeout/cancel | Transport errors unchanged. Observer failure leaves settled result intact and continues later observers even if logging fails. Transformation failure settles the derived task. Outcome attributes and physical completion remain separate. | task_result_spec; error_api_boundaries_spec; async composition suites |
+| C15 | Base.trace, trace_with, OpenTelemetry.trace, Automatic | Explicit tracing propagates start/finish-only failure. After a primary business failure finish is attempted once and secondary report failure is suppressed. No finish after start failure. OpenTelemetry keeps with_span context. Automatic retains best-effort observation policy; Langfuse keeps its adapter-specific network suppression. | tracing/base_spec; open_telemetry_tracer_spec; automatic and extension specs |
+| C16 | Filter.call/block!, PromptInjectionFilter | Keep explicit FilterBlockError and filter attribute; add optional constructor code. Implementation errors are not transformed into policy refusal. No unnecessary common rejection hierarchy. | filter specs; error_api_diagnostics_spec |
+| C17 | JsonParser.parse, StructuredParser.parse | Keep ParseError for JSON and documented ArgumentError/TypeError schema-instantiation rejection. Other schema bugs pass through. User schemas should raise domain-specific errors when they must not be treated as mapping rejection. No blanket StandardError rescue added. | output_parser specs; schema integration |
+| M91 | OrderedEventDelivery.publish/open/drain | ClosedError/OverflowError now inherit Phronomy::Error and report delivery.closed / delivery.capacity_exceeded. StandardError rescue still works; Phronomy::Error rescue now includes them. Reporting failure cannot replace an application error. No automatic resend. | ordered_event_delivery specs; error_api_boundaries_spec |
+| I05/I06/I07/I09 | Concrete binding, AsyncClients, runtime admission/shutdown | Preserve backend-specific failures and execution admission/timeout categories. No new reverse references into domain contracts. | architecture gate; backend/execution integration |
+| Other concrete helpers | Documents loaders, tools, evaluation and configuration | Preserve documented external operation errors and configuration checks; do not manufacture an application-wide ErrorTranslator. Generic Tool conversion applies when called through its public contract. | concrete tool/document/evaluation suites |
+
+## Diagnostic format and recovery
+
+Top-level `class`, `message` and optional `code` remain unchanged. An optional
+`cause` object transports the same neutral fields. New cause data is bounded to
+three ancestors and 2,048 characters per field. A further cause is represented
+by `{ "truncated": true }`; an oversized code is omitted, never shortened into
+another valid-looking code. Old top-level message behavior is unchanged.
+Backtraces, arbitrary exception attributes and live objects are not serialized.
+
+Agent and Team recovery use the same H00 decoder. It constructs only generic
+Phronomy::Error values, including their optional causes, and never constantizes
+saved names. Unknown/nil codes are retained. A restored cause is diagnostic data,
+not the original exception object or its domain-specific attributes. Applications
+may inspect `error.cause&.code` without depending on a storage exception class.
+The live exception still retains its exact original cause.
+
+## Migration and before/after use
+
+Before, a broad Persistence/Storage NotFound rescue could mistake a broken
+transcript for a missing Agent. After, limit creation to the requested identity:
+
+```ruby
+begin
+  agent = ConversationAgent.load(agent_id, persistence: store)
+rescue Phronomy::AgentNotFoundError => error
+  raise unless error.agent_id == agent_id.to_s
+  agent = ConversationAgent.create(agent_id: agent_id, persistence: store)
+end
+# A later transcript failure is not handled as Agent absence.
+messages = PhronomyExamples::TranscriptMessages.read(agent)
+```
+
+Before, an application handled a busy Team by rescuing AgentBusyError. After:
+
+```ruby
+begin
+  team.invoke(input)
+rescue Phronomy::MultiAgent::TeamBusyError => error
+  # Application decides whether to expose an existing run or defer new work.
+  show_active_team(error.team_id)
+end
+```
+
+Before, Embeddings::TransportError alone required SDK knowledge to distinguish
+credentials and quota. After, both remain catchable through TransportError:
+
+```ruby
+begin
+  vector = embeddings.embed(text)
+rescue Phronomy::Embeddings::AuthenticationError
+  request_credentials
+rescue Phronomy::Embeddings::RateLimitError
+  display_limit
+rescue Phronomy::Embeddings::TransportError => error
+  report_provider_failure(error)
+end
+```
+
+These are application choices, not core-provided UI or automatic retry helpers.
+For Tool failures the application code need not change: `error.cause` now works
+for late async failures too. New reason codes are additive; custom ToolError
+instances pass through with their original nil/unknown code.
+
+| Existing consumer | Migration / compatibility |
+|---|---|
+| Persistence::NotFoundError rescue around Agent/Team load | Still catches the new subclass; narrow it to the domain type and target ID for create-on-absence |
+| Storage::NotFoundError rescue around Agent load | Already crossed the wrong boundary; update as the examples do |
+| AgentBusyError rescue for Team's own admission | Change to MultiAgent::TeamBusyError; this is an intentional rescue-set change |
+| JSON::ParserError rescue around content.fetch_json | Change to ContentStore::IntegrityError and inspect code; original ParserError is cause |
+| Embeddings::TransportError rescue | Still catches both new subclasses |
+| Phronomy::Error rescue around optional delivery | Now includes ClosedError/OverflowError; evaluate the application's handling |
+| Exact equality of saved diagnostic hashes | Allow/test the optional cause object. Existing keys/codes and old JSON remain readable |
+| Error message parsing or class-name constantization | Use public categories/codes for live failures; generic decoded diagnostics for recovery |
+| Generic error logger retrying any error | Review separately; code/type does not prove rollback or idempotence |
+
+## Dependency acceptance
+
+No new Contract is introduced. New types live with C01/C04/C11; M91 remains an
+optional consumer. C04/C01 specialize C07's absence category using existing
+forward dependencies. H00 has no new domain reference. C05 uses C15's public
+SPI wrapper rather than a private helper. C09/C10/C11 do not borrow each other's
+error types. Ruby and RBS dependency graphs, not just Contract counts, are checked
+by the existing architecture tool. See the generated audit for candidate tree
+and exact deltas; the separate Contract diagram must describe the candidate as
+unmerged until adoption is verified.
+
+### Correction to the earlier Contract count
+
+The baseline and candidate both have **32**, not 30, static Contract pairs.
+The previous report omitted the existing RBS-only C01 → C08 references in
+`sig/phronomy/multi_agent/store.rbs` (Store/_Records.contents) and C05 → C08
+in `sig/phronomy/context.rbs` (Assembly.store). Both name the C08-owned
+`_ContentRepository` interface. These are valid forward public-contract
+references, not implementation dependencies introduced by this patch.
+The candidate diagram restores these two edges and labels the correction.
+
+At directory level the union still has 273 pairs, but two entries change:
+M91 integrations → H00 common is added; multi_agent/persistence → agent is
+removed because Team admission now owns its BusyError. Equal totals alone
+would conceal this responsibility improvement. The 32 Contract pairs are
+unchanged and acyclic; Ruby+RBS architecture validation passes.
+
+## Static exception inventory
+
+Ripper inspected 339 Ruby files. The following 63 definitions include base, private and optional-integration types; this is not a count of public APIs. Ruby declarations establish ownership. Existing RBS definitions and new owning-domain signatures are checked together.
+
+| Class | Parent | Declaration |
+|---|---|---|
+| `Phronomy::AgentAlreadyExistsError` | `Phronomy::Error` | `lib/phronomy/agent/agent_already_exists_error.rb` |
+| `Phronomy::AgentBusyError` | `Phronomy::Error` | `lib/phronomy/agent/agent_busy_error.rb` |
+| `Phronomy::AgentNotFoundError` | `Phronomy::Persistence::NotFoundError` | `lib/phronomy/agent/agent_not_found_error.rb` |
+| `Phronomy::AgentPurgedError` | `Phronomy::Error` | `lib/phronomy/agent/agent_purged_error.rb` |
+| `Phronomy::ExecutionRehydrationRequiredError` | `Phronomy::Error` | `lib/phronomy/agent/api/execution_rehydration_required_error.rb` |
+| `Phronomy::HandoffError` | `Phronomy::Error` | `lib/phronomy/agent/handoff_error.rb` |
+| `Phronomy::Agent::RecoveryCoordinator::ResolutionOutcomeUnknownError` | `Phronomy::Error` | `lib/phronomy/agent/recovery/recovery_coordinator.rb` |
+| `Phronomy::StreamCallbackError` | `Phronomy::Error` | `lib/phronomy/agent/stream_callback_error.rb` |
+| `Phronomy::ConfigurationError` | `Phronomy::Error` | `lib/phronomy/common/configuration_error.rb` |
+| `Phronomy::Error` | `StandardError` | `lib/phronomy/common/error.rb` |
+| `Phronomy::ContentStore::IntegrityError` | `Phronomy::Error` | `lib/phronomy/content_store/base.rb` |
+| `Phronomy::Context::BudgetExceededError` | `Phronomy::Error` | `lib/phronomy/context/budget_exceeded_error.rb` |
+| `Phronomy::Context::ManifestError` | `Phronomy::Error` | `lib/phronomy/context/manifest_error.rb` |
+| `Phronomy::Embeddings::AuthenticationError` | `Phronomy::Embeddings::TransportError` | `lib/phronomy/embeddings/authentication_error.rb` |
+| `Phronomy::Embeddings::InvalidResultError` | `Phronomy::Error` | `lib/phronomy/embeddings/invalid_result_error.rb` |
+| `Phronomy::Embeddings::RateLimitError` | `Phronomy::Embeddings::TransportError` | `lib/phronomy/embeddings/rate_limit_error.rb` |
+| `Phronomy::Embeddings::TransportError` | `Phronomy::Error` | `lib/phronomy/embeddings/transport_error.rb` |
+| `Phronomy::BackpressureError` | `Phronomy::Error` | `lib/phronomy/execution/backpressure_error.rb` |
+| `Phronomy::CancellationError` | `Phronomy::Error` | `lib/phronomy/execution/cancellation_error.rb` |
+| `Phronomy::EventLoopReentrancyError` | `Phronomy::Error` | `lib/phronomy/execution/event_loop_reentrancy_error.rb` |
+| `Phronomy::ExecutionCancellationError` | `Phronomy::CancellationError` | `lib/phronomy/execution/execution_cancellation_error.rb` |
+| `Phronomy::ExecutionTimeoutError` | `Phronomy::TimeoutError` | `lib/phronomy/execution/execution_timeout_error.rb` |
+| `Phronomy::InvalidAsyncEntryActionError` | `Phronomy::InvalidAsyncWorkflowActionError` | `lib/phronomy/execution/invalid_async_entry_action_error.rb` |
+| `Phronomy::InvalidAsyncTransitionActionError` | `Phronomy::InvalidAsyncWorkflowActionError` | `lib/phronomy/execution/invalid_async_transition_action_error.rb` |
+| `Phronomy::InvalidAsyncWorkflowActionError` | `Phronomy::Error` | `lib/phronomy/execution/invalid_async_workflow_action_error.rb` |
+| `Phronomy::PoolShutdownError` | `Phronomy::Error` | `lib/phronomy/execution/pool_shutdown_error.rb` |
+| `Phronomy::RecursionLimitError` | `Phronomy::Error` | `lib/phronomy/execution/recursion_limit_error.rb` |
+| `Phronomy::RuntimeShutdownError` | `Phronomy::Error` | `lib/phronomy/execution/runtime_shutdown_error.rb` |
+| `Phronomy::RuntimeShutdownReentrancyError` | `Phronomy::RuntimeShutdownError` | `lib/phronomy/execution/runtime_shutdown_reentrancy_error.rb` |
+| `Phronomy::SchedulerReentrancyError` | `Phronomy::EventLoopReentrancyError` | `lib/phronomy/execution/scheduler_reentrancy_error.rb` |
+| `Phronomy::TimeoutError` | `Phronomy::Error` | `lib/phronomy/execution/timeout_error.rb` |
+| `Phronomy::FilterBlockError` | `Phronomy::Error` | `lib/phronomy/filter/filter_block_error.rb` |
+| `Phronomy::LowConfidenceError` | `Phronomy::Error` | `lib/phronomy/generation/low_confidence_error.rb` |
+| `Phronomy::Integrations::OrderedEventDelivery::ClosedError` | `Phronomy::Error` | `lib/phronomy/integrations/ordered_event_delivery.rb` |
+| `Phronomy::Integrations::OrderedEventDelivery::OverflowError` | `Phronomy::Error` | `lib/phronomy/integrations/ordered_event_delivery.rb` |
+| `Phronomy::LLMAdapter::AuthenticationError` | `Phronomy::LLMAdapter::TransportError` | `lib/phronomy/llm_adapter/authentication_error.rb` |
+| `Phronomy::LLMAdapter::RubyLLM::ToolsRequested` | `StandardError` | `lib/phronomy/llm_adapter/backends/ruby_llm.rb` |
+| `Phronomy::LLMAdapter::ContextLengthError` | `Phronomy::Error` | `lib/phronomy/llm_adapter/context_length_error.rb` |
+| `Phronomy::LLMAdapter::InvalidResultError` | `Phronomy::Error` | `lib/phronomy/llm_adapter/invalid_result_error.rb` |
+| `Phronomy::LLMAdapter::RateLimitError` | `Phronomy::LLMAdapter::TransportError` | `lib/phronomy/llm_adapter/rate_limit_error.rb` |
+| `Phronomy::LLMAdapter::TransportError` | `Phronomy::Error` | `lib/phronomy/llm_adapter/transport_error.rb` |
+| `Phronomy::MultiAgent::TeamBusyError` | `Phronomy::Error` | `lib/phronomy/multi_agent/team_busy_error.rb` |
+| `Phronomy::MultiAgent::TeamCoordinator::OperationRejected` | `Phronomy::ConfigurationError` | `lib/phronomy/multi_agent/team_coordinator.rb` |
+| `Phronomy::MultiAgent::TeamNotFoundError` | `Phronomy::Persistence::NotFoundError` | `lib/phronomy/multi_agent/team_not_found_error.rb` |
+| `Phronomy::ParseError` | `Phronomy::Error` | `lib/phronomy/output_parser/parse_error.rb` |
+| `Phronomy::Persistence::Error` | `Phronomy::Error` | `lib/phronomy/persistence/errors.rb` |
+| `Phronomy::Persistence::ConflictError` | `Phronomy::Persistence::Error` | `lib/phronomy/persistence/errors.rb` |
+| `Phronomy::Persistence::StateConflictError` | `Phronomy::Persistence::ConflictError` | `lib/phronomy/persistence/errors.rb` |
+| `Phronomy::Persistence::NotFoundError` | `Phronomy::Persistence::Error` | `lib/phronomy/persistence/errors.rb` |
+| `Phronomy::Persistence::SerializationError` | `Phronomy::Persistence::Error` | `lib/phronomy/persistence/errors.rb` |
+| `Phronomy::Persistence::UnsupportedBackendError` | `Phronomy::Persistence::Error` | `lib/phronomy/persistence/errors.rb` |
+| `Phronomy::Persistence::TransactionError` | `Phronomy::Persistence::Error` | `lib/phronomy/persistence/errors.rb` |
+| `Phronomy::Storage::BlobConflictError` | `Phronomy::Storage::ConflictError` | `lib/phronomy/storage/blob_conflict_error.rb` |
+| `Phronomy::Storage::ConditionFailedError` | `Phronomy::Storage::ConflictError` | `lib/phronomy/storage/condition_failed_error.rb` |
+| `Phronomy::Storage::ConflictError` | `Phronomy::Error` | `lib/phronomy/storage/conflict_error.rb` |
+| `Phronomy::Storage::NotFoundError` | `Phronomy::Error` | `lib/phronomy/storage/not_found_error.rb` |
+| `Phronomy::Storage::SerializationError` | `Phronomy::Error` | `lib/phronomy/storage/serialization_error.rb` |
+| `Phronomy::Storage::TransactionError` | `Phronomy::Error` | `lib/phronomy/storage/transaction_error.rb` |
+| `Phronomy::Storage::UniqueConstraintError` | `Phronomy::Storage::ConflictError` | `lib/phronomy/storage/unique_constraint_error.rb` |
+| `Phronomy::Storage::UnsupportedBackendError` | `Phronomy::Error` | `lib/phronomy/storage/unsupported_backend_error.rb` |
+| `Phronomy::ToolError` | `Phronomy::Error` | `lib/phronomy/tool/tool_error.rb` |
+| `Phronomy::VectorStore::InvalidResultError` | `Phronomy::Error` | `lib/phronomy/vector_store/invalid_result_error.rb` |
+| `Phronomy::WorkflowContextOwnershipError` | `Phronomy::Error` | `lib/phronomy/workflow/execution/workflow_context_ownership_error.rb` |
+| `Phronomy::WorkflowTaskResumeError` (DX05-D) | `Phronomy::Error` | `lib/phronomy/workflow/execution/workflow_task_resume_error.rb` |

data/docs/architecture/execution-abstraction-review.md

@@ -0,0 +1,88 @@
+# Execution abstraction revision (local review candidate, 2026-09-29)
+
+This candidate supersedes the unapplied Results split. It is based on main
+653e255a, with the earlier execution-boundary prototype included. It is not a
+record of application to main. The historical D02 reports describe their original
+revisions; the control ownership decision below supersedes them for this candidate.
+
+## Responsibilities
+
+| Owner | Owns | Consumers should know |
+|---|---|---|
+| Execution Contracts (G58, B5) | Context, TaskResult/Outcome, cancellation/deadline values, shared errors, neutral scope/result implementation | Public inputs, result handles and errors |
+| Execution Services (G59, B4) | Fan-out, child control lifetime, invocation admission checks, completion adaptation, worker submission and deadline registration | Start/observe APIs and domain value/error policies |
+| Engine Internals (G14, B5) | Runtime resources, EventLoop, FSMSession | Only runner/lifecycle/composition owners connect here |
+| Engine Concurrency (G61, B5) | Pools and queues | Engine supplies scheduling and wait-policy context |
+
+Bands are visual organization, not a dependency order. Backend Contracts remain
+in B5. `execution_contract/errors`, `execution_result` and
+`execution_result/concurrency` are removed. Their neutral implementation is
+integrated into the existing `execution_contract` and its `concurrency` child.
+M79/M80/M81 and G60 are retired. TaskResult is not returned to Services: doing so
+would recreate Engine→Services. The two contract directories remain mutually
+referencing within G58; the design does not claim zero cycles or pure declarations.
+
+## Actual hiding, beyond renaming dependency hubs
+
+| Consumer | Previous knowledge | Current entry point |
+|---|---|---|
+| Agent::ExecutionCoordinator | Extracted context scope, checked open/cancelled state, selected scope error | InvocationControls.attach + check_start!; Agent still owns admission and its result production |
+| MultiAgent::Orchestrator | Called Execution's private fan-out, constructed OperationBinding, linked tokens, selected context, closed subscriptions | Execution.run_async(max_concurrency:) + start_child; supplies child invocation |
+| Tools::Agent / generated subagent tools | Created deferred result and relayed completion/failure callbacks | AsyncOperation.call/capture; supplies output/error policy |
+| Agent::ToolBinding | Called TaskResult.__map_completion, a special internal composition path | AsyncOperation.map; supplies filters |
+| Workflow builder (earlier included change) | Used FSM's finish vocabulary | Workflow::Completion; runner translates to FSM |
+
+InvocationControls extends the existing service helper and absorbs the removed
+OperationBinding's lifetime logic. It is not a pass-through factory that still
+forces callers to manage cleanup. AsyncOperation encapsulates notification
+multiplicity, startup/transformation failure, and physical completion. Domain
+consumers still legitimately depend on TaskResult return types and cancellation
+inputs; hiding those via aliases would not improve the abstraction.
+
+ExecutionCoordinator, WorkflowRunner and durable reconciliation coordinators
+remain result producers. Their lifecycle, registry and terminal policy code has
+not all been turned into a generic facade. The public user-facing async APIs and
+backend contracts retain their namespaces.
+
+## Investigation heuristic
+
+Detect each M0→M1, M1→M2, M0→M2 triangle in the complete Ruby + RBS graph.
+Prioritize adjacent descending display bands, then other descending bands, then
+all remaining graph triangles. Keep sidebar modules and visually hidden arrows.
+Do not remove edges or make a triangle a CI violation solely on that basis.
+
+For M0's direct M2 usage, inspect its actual source operation:
+
+- Internal detail: Orchestrator linked child tokens and closed subscriptions;
+  Execution now owns this through start_child.
+- Connection: a runner registers its session with Runtime; this can belong to
+  that runner. Move it only if its current owner mixes unrelated responsibilities.
+- Shared/public contract: AsyncClient returns TaskResult and callers handle its
+  result. Keep the declared RBS dependency instead of erasing the type.
+
+Multiple M1 paths may identify the same direct edge. Reports include both the
+triangle count and the number of distinct M0→M2 pairs. RBS-only direct edges are
+marked, not automatically accepted. Directory aggregation can combine different
+classes/functions, so a graph path is not proof of a call chain. Dynamic dispatch
+can also leak details without any constant-reference triangle.
+
+`dependency_triangles.json` preserves all three edges' source evidence;
+`dependency_triangles.csv` is the review queue. Entries start as unreviewed.
+A separate narrow AST regression gate rejects the already-corrected private
+scope methods and selected consumers' manual result settlement. It does not
+purport to detect every possible abstraction leak.
+
+## Compatibility and verification scope
+
+Execution.run/run_async accept additive max_concurrency. No new backend methods
+are required from application authors. The included earlier candidate removes
+InvocationContext#effective_timeout_token/#effective_cancellation_token and the
+internal Deadline#attach_to, CancellationScope, old FSM vocabulary ownership.
+This revision removes internal OperationBinding and TaskResult.__map_completion.
+There are no backward aliases that point neutral contracts back at services.
+
+Tests cover bounded admission, cancellation before queued start, explicit child
+context identity, cleanup after completion/start failure, duplicate callback
+notifications, original error identity, recovery errors, and physical completion.
+Existing Agent, Tool, Workflow, persistence/recovery and async tests remain gates.
+The delivered evidence report records actual execution results and limitations.

data/docs/architecture/execution-boundaries.md

@@ -0,0 +1,28 @@
+# Execution dependency ownership
+
+Use the highest existing operation that expresses the caller's responsibility.
+A facade is useful when it owns real coordination, not just because it reduces
+arrows. These cases distinguish shared contracts from executable machinery.
+
+| Caller / operation | Dependency after this change | Decision |
+|---|---|---|
+| ToolBinding result filter | TaskResult private completion mapping | Remove duplicate physical-completion handling; source completion alone must not finish the filtered result |
+| Tracing span finish | Blocking.call_async | Generic default-pool work; observe rejection in the returned result |
+| Approval listener dispatch | Blocking.call_async | Generic default-pool work; log admission and later callback errors |
+| Agent/Workflow synchronous entry guard | Runtime.in_event_loop_context? | Query context without creating Runtime |
+| Prompt parser, Runnable users | Execution Contracts | Public callable/value contract, not pool internals |
+| Agent lifecycle/state, capability and journal input markers | Execution Contracts | Methodless classification; preserve direct include and validation |
+| Tool and async-client RBS token/result references | Execution Contracts / Execution Services | Keep real public type use in the graph; do not invent a domain facade for a token |
+| LLM, VectorStore, Embeddings and Storage AsyncClients | Contracts + TaskResult + Runtime/pools | Intended bridge; keep specialized submission, token and admission rules |
+| Agent ExecutionCoordinator / MultiAgent binding | Concurrency operation binding | Own cancellation/deadline scope across an operation; generic Blocking is not equivalent |
+| Agent and Workflow runners / execution registries | Runtime, FSM session and control delivery | Framework connection and single-writer ownership; retain these explicit dependencies |
+| Engine worker pool | TaskResult and execution errors | Produces shared results; the service/Engine relationship is not acyclic |
+
+The full dependency graph still includes references through shared error classes,
+markers and RBS. Moving their source owners changes the interpretation of the
+old Engine fan-in; it does not remove their actual use. The architecture gate
+enforces Contracts-to-Contracts/Common only and rejects domain/backend/client
+dependencies from Services or Engine. Layout is independent of those rules.
+
+See [ADR-063](../decisions/063-execution-contracts-and-services.md) for the source
+layout, behavior change and compatibility boundary.

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

@@ -1,5 +1,11 @@
 # Shared execution metadata and value conversion
 
+> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
+> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
+> construction/interception; Tool owns canonical schema validation. See
+> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
+
+
 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

data/docs/architecture/multi-agent-handoff.md

@@ -24,14 +24,14 @@ Normative Handoff intent is
 with the Runner ownership amendment in
 [ADR-034](../decisions/034-handoff-runner-coordination-ownership.md).
 
-The Runner owns the cross-Agent turn. Handoff edges, Policy, Context and
-Agent terminal/persistence integration remain in Agent during this first
-migration step. See the [Runner migration](../migrations/handoff-runner-multi-agent.md).
+MultiAgent owns the cross-Agent turn, Handoff edges, Policy, routing and reservations.
+Agent owns generic control requests, finalized Context projection and its own
+execution commits. See [r8 unit 4](r8-unit4.md).
 
 ## 2. Public API
 
 ```ruby
-handoff = Phronomy::Agent::Handoff.new(
+handoff = Phronomy::MultiAgent::Handoff.new(
   source_agent: triage,
   target_agent: billing,
   description: "Transfer billing responsibility",
@@ -40,6 +40,7 @@ handoff = Phronomy::Agent::Handoff.new(
 
 runner = Phronomy::MultiAgent::HandoffRunner.new(
   main_agent: triage,
+  persistence: stores.multi_agent,
   handoffs: [handoff]
 )
 
@@ -56,7 +57,7 @@ schemas. The generated Tool name is private transport encoding, not Handoff
 identity or public semantic contract.
 
 Phronomy intercepts the Provider Tool Call into a typed private
-`HandoffRequest`. It does not execute an ordinary `ToolInvocation` or emit a
+`Agent::ControlRequest`. It does not execute an ordinary `ToolInvocation` or emit a
 sentinel Tool result.
 
 ## 4. Handoff Policy

data/docs/architecture/persistence.md

@@ -9,9 +9,11 @@
 
 ## 1. Durable boundary
 
-`Phronomy::Persistence` is the domain-facing service for the single durable-state
-transaction domain used by Agents, Teams, and Workflows. It composes a
-`Storage::Backend`; storage implementations do not inherit the domain service.
+`Phronomy::Persistence` owns domain-neutral atomic scopes over a `Storage::Backend`.
+`Agent::Store` and `MultiAgent::Store` own domain operations and result queries;
+Workflow consumes its checkpoint repository directly. These roles share a
+coordinator when operations must commit together. Storage implementations do not
+inherit a domain service. See [r8 unit 3](r8-unit3.md) for construction and migration.
 
 The `storage/` directory owns record carriers, portable errors, repository views,
 and the Backend contract. `storage/backends/` owns physical storage implementations.
@@ -20,13 +22,29 @@ directories own their domain codecs and repositories. Agent and Team result
 queries live with those domains. `storage/record_codec.rb` contains only shared
 record-envelope and scalar validation; it does not select a domain schema.
 `persistence_composition/` assembles the domain repositories over one raw view.
-The public `Phronomy::Persistence` entry point delegates to those components and
-retains its observation-thread guard.
-The root and transaction paths use the same facade construction, with transaction
-facades bound to the raw backend view for that transaction.
+`content_store/` is a content management service over Storage, not a physical
+backend family. Its Base shares text/JSON conversion with StoredContents and
+the Persistence content facade. StoredContents generates content IDs, verifies
+digest identity and uses the injected view's Blobs. Its StorageSchema belongs
+to this service. Storage owns byte immutability, transactions and physical I/O.
+The service and its schema live together; there is no `content_store/backends/`
+directory or backend-selection API. See [ADR-062](../decisions/062-content-store-service.md).
+Domain stores receive their record adapters from `PersistenceComposition` and
+retain their observation-thread guards. The common Persistence does not select
+domains, assemble repositories, or delegate domain result queries. Domain-only
+record protocols bind to the exact scope when participating; there is no shared
+all-domain repository facade.
 See [ADR-032](../decisions/032-storage-backend-composition.md) and
 [ADR-033](../decisions/033-domain-persistence-ownership.md).
 
+`persistence/errors.rb` owns the shared domain-facing failure classes. Repository
+boundaries translate four known raw Storage categories to Persistence categories,
+retaining the original exception as `cause`. Upper domain state contradictions
+use `Persistence::StateConflictError < Persistence::ConflictError`. Unknown and
+commit-outcome-uncertain exceptions are not reclassified. Backend contracts never
+depend on these upper errors. See [ADR-061](../decisions/061-persistence-failure-contracts.md)
+and the [rescue-clause migration](../migrations/persistence-failure-contracts.md).
+
 Shared value copying belongs to `Values::Immutable` in `values/`. Agent records,
 Team records, Recovery classifications, and Persistence result views use this
 internal helper without borrowing an Agent implementation. It copies and freezes
@@ -41,7 +59,7 @@ does not change record formats, transaction ownership, or recovery guarantees.
 | `agents` | AgentRoot |
 | `journals` | Append-only Agent journal |
 | `executions` | AgentExecution and owned child coordination |
-| `workflow_states` | Workflow snapshots |
+| Workflow checkpoint repository | Workflow snapshots |
 | `handoff_states` | Active responsibility and exact Target reservation |
 | `teams` | TeamRoot |
 | `team_executions` | Team tasks, assignments and outcomes |
@@ -93,7 +111,7 @@ Defined semantic durable transitions are atomic according to the Persistence
 transaction contract and conforming backend.
 
 Revision/watermark/CAS checks reject stale durable transitions with
-`Storage::ConflictError` rather than silently merging/reloading competing
+`Persistence::ConflictError` rather than silently merging/reloading competing
 state.
 
 Conflict detection is not competing-execution exclusion and cannot undo an

data/docs/architecture/r8-unit1.md

@@ -0,0 +1,104 @@
+# r8第1適用版：Context／ToolとExecutionの共通基盤
+
+> Current boundary: r8 unit 6 supersedes the historical Chat/SDK ownership and
+> adapter extension SPI below. Agent uses LLMAdapter values; the backend owns SDK
+> construction/interception; Tool owns canonical schema validation. See
+> `docs/architecture/r8-unit6.md` and `docs/migrations/r8-unit6.md`.
+
+
+対象は2026-09-30に確認したmain `653e255a34fe4062d4beca47530e084fdd3a6ba9`。設計基準は同日更新のr8修正仕様・directory配置資料である。本変更はその第1適用単位であり、r8全体、S1全項目、S2/S3全受入条件の完了を意味しない。互換alias・転送だけの旧APIは残さない。
+
+## 実装した責務と操作
+
+| 所有者 | 共通基盤が実行すること | 利用側に残すこと |
+|---|---|---|
+| `Context::Assembly` | Policyを一度呼びPlanを検証する。内容を正規化し、最終予算を検査してManifestを保存する | Agentはsnapshotを取得し、保存直前のwatermark再確認とAgent実行記録更新を行う |
+| `Tool::DefinitionSet` | Tool定義の正規化、名前重複と保存済み定義の整合性を検証する | Agentは自身のTool alias・decorator・runtime実体を準備する |
+| `Tool::Authorization` | 不変の引数・認可contextでfacts→requirement→policy→decisionを評価する | Agentは対象実行の照合、承認状態、受付結果、supervisionを管理する |
+| `Tool::ToolExecutor` | cooperative/offloadedの実行規則と結果を扱う | Engineのpool選択はExecutionの機構接続へ委ねる |
+| `LLMAdapter::Base` / `RubyLLM` | 同期生成とchat構築・設定・message/tool-call構築。RubyLLM実装がSDK失敗を変換する | Agentは自身の保存データ・Tool定義を検証してadapterへ渡す |
+| `Execution` | submitの入口、fan-out/fan-in、結果合成、取消・期限・待機規則 | Engineはpool・timer・RuntimeとFSMの機構を実装する |
+| `Tracing::Observation` | 明示的な観測とPII秘匿。実際の返り値は変えない | Runnableはinvoke/stream/batchの実行契約を持つ |
+
+ContextとToolはAgentの薄い型定義の置場ではなく、実際の共通手順を所有する。ただし、Contextの現在の入力にはAgent由来の識別情報や由来情報が残る。完全に汎用の新domainモデルまで設計し直したものではない。ToolのDSL基底は引き続きRubyLLM::Toolを使用する。
+
+`Context::Assembly#prepare(input:, policy:, adapter_identity:)` は保存transaction外でPolicyを呼ぶ。`#store(prepared, contents:)` は呼出側が渡す同じtransactionのcontents repositoryだけを使い、自分では独立transactionを開始しない。初回とfollow-upのAgent commitは既存transaction内でManifestとAgentExecutionの参照を保存する。後続書込に失敗したときManifestもrollbackされ、Policyは再実行されない。live projectionをcommit後に適用する既存順序を維持する。これはP02のAgent／Context部分の検証であり、任意domainの外側transaction参加を完成させたものではない。
+
+Executionは`_ExecutionBackend`の操作に依存する。構成処理が遅延providerを設定し、Engineの`ExecutionBinding`がsubmit/afterを実装する。settled TaskResultの生成・map/flat_map/all_settled・待機制約の確認ではEngineを読み込まない。Runtime取得は実際のsubmit/タイマー登録時に行う。単なる名義移管に留めず、機構参照をここへ集約した。
+
+WorkflowのFINISHと終了値は`Workflow::Completion`が所有し、WorkflowRunnerがFSM側へ変換する。FSMSession専用のEvent／FSMProtocol／TerminalDecisionはEngineに置く。Agent・MultiAgentのFSM専用接続の全面分離は残っている。
+
+## 公開名・配置の変更
+
+| 旧配置・API | 新配置・API | 判断 |
+|---|---|---|
+| `agent/context_contract/` と `Agent::ContextPolicy` 等 | `context/`、`Context::ContextPolicy` 等 | Policy・Plan・Manifest・検証を共通操作と同じ所有者へ統合 |
+| `agent/context_policies/default.rb` | `context/default_policy.rb`、`Context::DefaultPolicy` | 具体Policyも同domainに配置 |
+| `Agent::Context::Instruction::PromptTemplate` | `Context::PromptTemplate` | Agent内の旧公開名を削除 |
+| `Agent::Selection::{Candidate,Constraint}` | `Context::{Candidate,Constraint}` | 薄いSelection下位区分を削除 |
+| `Agent::LLMInputPatch` / `LLMInputBuildContext` | `Context::LLMInputPatch` / `LLMInputBuildContext` | hook入力・返却値の所有を統一 |
+| `ContextBudgetExceededError` | `Context::BudgetExceededError` | LLMのprovider失敗ではなくContext予算失敗 |
+| `agent/context_assembly/` | `context/assembly.rb` とAgent直下の準備・状態・入力処理 | Context共通手順、Agent snapshot/state、LLM SDK処理を分離 |
+| `Agent::Context::Capability::Base` | 実装本体の `Tool::Base` | 旧名とaliasを削除 |
+| `agent/tool_execution/tool_definition_set.rb` | `tool/definition_set.rb` | 共通定義処理を移管。Agent固有生成はAgent内 |
+| `execution_contract/` と `execution_services/` | `execution/` と必要な `execution/concurrency/` | 操作・値・共通規則を統合。`execution_result`等の薄い別分割を追加しない |
+| `WorkerSubmission` | `Execution.submit` | 転送専用moduleを削除 |
+| `Runnable#trace` | `Tracing::Observation.trace` | 実行基盤から観測への依存を除去 |
+| `tool/contract`、`filter/contract`、`output_parser/contract`、`agent/lifecycle_contract` | 各所有domain配下の例外ファイル | 例外だけのdirectoryを削除。既存の意味を持つ例外定数名は実体として保持 |
+
+独自LLM adapterはcomplete/streamだけでなく、`build_chat`、`configure_chat`、`message`、`tool_call`を実装する。`identity`には基底の既定値、`input_budget`にはnilの既定値がある。正確なkeywordと返却契約は`sig/phronomy/llm_adapter/base.rbs`を参照する。SDK固有例外はadapter操作の境界でLLM失敗へ変換し、元のcauseを保持する。アプリ例外・取消は無関係なprovider失敗へ変換しない。
+
+既存設定APIの`tool_result_max_size`／loggerはアプリ構成から中立RuntimeSettingsへ供給する。Toolから構成factoryへの参照を除き、default・nil・scoped copyの意味を維持する。RBSは`sig/`と`sig/_private/`に置き、実装定数・宣言所有者に基づいて依存を解析する。
+
+## r8項目別の到達点
+
+| 項目 | この適用版 | 未完了部分 |
+|---|---|---|
+| DP01 Context集約 | 主対象を実装 | より広いdomain入力・公開操作レビューは残る |
+| DP02 Tool共通基盤 | 定義・認可評価・呼出しの共通部分を実装 | Agent側FSM接続と全親子認可の整理はDP12/P04 |
+| DP03 Execution統合 | 実装 | domain全体のFSM利用整理を完了としない |
+| DP04 Persistence | 未着手 | facade除去、共通transaction/参加/成否照合API |
+| DP05 domain保存schema | 未着手 | MultiAgent/Workflowのstorage_contract統合 |
+| DP06 LLM集約 | 前提部分のみ | llm_contractとllm_adapterの全面統合 |
+| DP07 薄い失敗directory統合 | 実装 | domainごとの失敗語彙全体の再設計ではない |
+| DP08 composition集約 | 接続追加のみ | runtime/persistence/agent構成の物理統合 |
+| DP09 Embeddings独立 | 未着手 | vector_storeからの独立配置 |
+| DP10 Documents | 未着手 | loader/splitter再配置 |
+| DP11 assembly/concerns分解 | 主対象を実装 | Agent固有処理はAgent直下に保持 |
+| DP12 domain実行接続 | Workflow終了境界など一部 | Agent/ToolInvocation/Teamのdomain判断とFSM接続の全面分離 |
+| DP13 Recovery/Handoff | 未着手 | domain復旧・Persistence成否照合・親子操作の所有整理 |
+| P02保存参加 | Agent/Contextの既存transactionで検証 | 外側scope、savepoint、複数domainの公開参加API |
+| P01/P03〜P06保存・親子連携 | 未着手 | 下記の原子性条件を確定する必要がある |
+| 155組・393件の三角形レビュー | 再判定未完了 | 図の再解析は判定完了の代わりにはならない |
+
+NC/F/RMの全項目を「対応済み」とする資料は作成していない。受入可否はこの表の実装単位と同梱テスト証拠に限定する。
+
+## Persistenceをこの適用単位から外した理由
+
+現在のAgent初回受付は保存transaction内でTeam予約を読む。AgentからTeam内部への参照は最終設計では解消すべきだが、検証を単純に先行呼出へ移すと次の競合が生じる。
+
+1. 親側が予約の有効性を確認する。
+2. 別の処理が予約を取り消す。
+3. Agentが新しいtransactionで受付記録を保存し、取消済みの子を開始してしまう。
+
+次の適用単位では、親が所有する予約確認とAgent受付記録を同一scopeで行う参加APIが必要である。親は予約規則、Agentは受付規則、Persistenceは参加とcommit境界を所有する。Agentが親kindをswitchしてTeamを選ぶ現在の逆依存を、新しいcallbackの裏へ隠すだけでは解決にならない。
+
+具体的に未確定なのは、参加操作の公開keyword/返却値、取消との競合条件、commit後のRuntime admission、停止後の同じ子IDによる照会・再開である。Workflowのhalt/finish snapshotだけで任意action内の子実行が耐障害化されるとは扱わない。Workflow→Agent/Teamの具体経路、checkpoint、結果取込一回性をP05で定める。成否不明は単一record一致だけで成功にせず、複数domainの証拠をP06で定める。
+
+そのため既存Persistence facade、Team受付検証、予約・子記録のtransaction境界を本変更では改変しない。保証を弱めた仮実装を入れず、次の仕様・実装単位として残す。
+
+## 解析図の読み方
+
+実ソースとRBSから再生成する。従来の水平帯・グループ色・個別module枠を維持し、文字の背景は透過。M33/M41/M44への矢印は表示のみ省略し、JSON・行列・境界判定にはすべて残す。旧IDは再利用せず退役させる。
+
+これは修正版candidateの実測図であり、全r8完了時の構想図ではない。残る循環・逆依存もそのまま出力する。静的解析で見えない注入先・動的dispatchはRBSだけで完全に証明できない。Engine機構接続とdomain保存の実行テストを併用する。
+
+```bash
+bundle exec rbs -I sig validate
+python -m pip install -r tools/architecture/tools/requirements.txt
+python -m unittest discover -s tools/architecture/tests -v
+# lib/sigをcommitした後、未公開candidateでは次の指定を用いる
+python tools/architecture/refresh_diagram.py . tmp/architecture-r8-unit1 --candidate
+```
+
+同梱SVGのSHAは作成用のローカルcandidateを示す。利用者が適用してcommitしたSHAとは異なるため、適用後の図はそのcheckoutで再生成する。Rubyの検証環境、件数、skip理由、未検証環境と適用手順は配布パッケージの検証報告を参照する。