phronomy 0.22.0 → 0.23.0

data/docs/archive/design/archived/17_rails_integration.md

@@ -0,0 +1,175 @@
+> **ARCHIVED / non-normative**
+>
+> This removed/obsolete design is retained only as historical reference. It is
+> not a current architecture or public-API contract. Start at
+> [docs/architecture.md](../../../architecture.md) and the
+> [ADR index](../../../decisions/README.md).
+
+# Phronomy — Rails Integration
+
+> **Archived.** Rails integration (`Railtie`, `acts_as_phronomy_message`,
+> install generator, `AgentJob`) was removed in v0.3.0–v0.5.1. This document
+> no longer describes the current public API and is preserved for historical
+> reference only.
+
+## 1. Overview
+
+`phronomy-rails` provides first-class Rails integration:
+
+- `AgentJob` — run agents asynchronously with real-time streaming via ActionCable
+- `Railtie` — auto-require phronomy components when Rails+ActiveRecord loads
+- `acts_as_phronomy_message` — ActiveRecord mixin for storing LLM messages
+- Generator — scaffolds database tables and initialiser
+
+---
+
+## 2. Railtie
+
+`lib/phronomy/railtie.rb`
+
+Registered automatically when `phronomy` is added to the Gemfile in a Rails
+app. Hooks into `ActiveSupport.on_load(:active_record)` to:
+
+1. Require `phronomy/state_store/active_record`
+2. Require `phronomy/rails/acts_as_phronomy_message`
+
+No manual `require` is needed in `config/application.rb`.
+
+---
+
+## 3. AgentJob
+
+`lib/phronomy/rails/agent_job.rb`
+
+An `ActiveJob::Base` subclass that runs a phronomy agent and optionally streams
+events to an ActionCable channel.
+
+### Class method
+
+```ruby
+MyAgentJob.perform_later(
+  agent_class: "PolicyAgent",     # String — constantized at runtime
+  input:       "What is policy?",
+  channel:     "ConversationChannel",  # ActionCable channel class name
+  stream:      "conversation_42",      # ActionCable stream name
+  config:      { thread_id: "t1" }     # forwarded to agent.invoke
+)
+```
+
+### Event protocol
+
+Events are broadcast to `stream` via `ActionCable.server.broadcast`:
+
+```json
+{ "type": "token",   "content": "..." }
+{ "type": "done",    "output":  "full answer" }
+{ "type": "error",   "message": "error description" }
+```
+
+Token events are emitted during streaming (if the agent supports `stream:`).
+The `done` event is emitted after the full output is available.
+The `error` event is emitted if the agent raises an exception.
+
+### Perform method
+
+```ruby
+def perform(agent_class:, input:, channel: nil, stream: nil, config: {})
+  agent = agent_class.constantize.new
+  output = agent.invoke(input, config: config)
+  broadcast(channel, stream, type: "done", output: output[:output]) if channel
+rescue => e
+  broadcast(channel, stream, type: "error", message: e.message) if channel
+  raise
+end
+```
+
+---
+
+## 4. acts_as_phronomy_message
+
+`lib/phronomy/rails/acts_as_phronomy_message.rb`
+
+ActiveRecord mixin. Adds a `role` enum, `content` accessor, and helper scopes.
+
+```ruby
+class Message < ApplicationRecord
+  acts_as_phronomy_message
+end
+```
+
+**Expected columns:**
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `role` | `integer` | `:system`, `:user`, `:assistant`, `:tool` |
+| `content` | `text` | Message content |
+| `thread_id` | `string` | Groups messages by conversation |
+| `tool_call_id` | `string` (optional) | For tool result messages |
+
+**Scopes added:**
+
+| Scope | Description |
+|-------|-------------|
+| `for_thread(id)` | Filter by `thread_id` |
+| `conversation_order` | Order by `created_at ASC` |
+| `as_phronomy_messages` | Returns an Array of `{role:, content:}` hashes |
+
+---
+
+## 5. Database Schema
+
+Generated by `rails generate phronomy:install`:
+
+### `phronomy_states`
+
+```sql
+CREATE TABLE phronomy_states (
+  id         BIGINT PRIMARY KEY AUTO_INCREMENT,
+  thread_id  VARCHAR(255) NOT NULL,
+  state_json TEXT         NOT NULL,
+  created_at DATETIME,
+  updated_at DATETIME,
+  UNIQUE INDEX idx_phronomy_states_thread_id (thread_id)
+);
+```
+
+### `phronomy_messages`
+
+```sql
+CREATE TABLE phronomy_messages (
+  id          BIGINT PRIMARY KEY AUTO_INCREMENT,
+  thread_id   VARCHAR(255) NOT NULL,
+  role        INTEGER      NOT NULL,
+  content     TEXT         NOT NULL,
+  tool_call_id VARCHAR(255),
+  created_at  DATETIME,
+  updated_at  DATETIME,
+  INDEX idx_phronomy_messages_thread_id (thread_id)
+);
+```
+
+---
+
+## 6. Generator
+
+`lib/generators/phronomy/install_generator.rb`
+
+```bash
+rails generate phronomy:install
+```
+
+Creates:
+- `db/migrate/<timestamp>_create_phronomy_tables.rb` (both tables above)
+- `config/initializers/phronomy.rb` (skeleton Phronomy.configure block)
+
+---
+
+## 7. Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| `AgentJob` uses string class name for `agent_class` | ActiveJob serialises arguments to JSON; class references must be strings |
+| Railtie hooks into `on_load(:active_record)` | Avoids eager-loading AR models before the app is ready |
+| `acts_as_phronomy_message` is a mixin, not a base class | Apps may extend their own Message model; mixin is less invasive |
+| Generator creates both tables | Convenience; apps can remove the table they don't need |
+| Broadcast `type:` field | Allows clients to handle events polymorphically without type sniffing |

data/docs/archive/design/historical/00_design_philosophy.md

@@ -0,0 +1,122 @@
+> **HISTORICAL / non-normative snapshot**
+>
+> Preserved as design history. This document does not define current Phronomy
+> architecture or public compatibility. Start at
+> [docs/architecture.md](../../../architecture.md) and the
+> [ADR index](../../../decisions/README.md).
+
+# Ruby AI Agent Framework — Design Philosophy and Goals
+
+## 1. Overview
+
+This framework (working name: **Phronomy**) is an AI agent construction framework for the Ruby ecosystem that provides functionality equivalent to LangChain and LangGraph. It leverages the `ruby_llm` gem for LLM communication and aims to deliver chain composition, state-graph execution, memory management, and multi-agent coordination through a Ruby-idiomatic DSL.
+
+---
+
+## 2. Problems We Are Solving
+
+Currently, the Ruby/Rails ecosystem lacks a framework that provides the following features in an integrated way.
+
+| Feature | Python Options | Ruby Status |
+|---|---|---|
+| LLM Abstraction | LangChain Core, LiteLLM | RubyLLM (available) |
+| Chain Composition | LangChain LCEL | **implemented** (`Chain`) |
+| State Graph Execution | LangGraph StateGraph | **implemented** (`Workflow` DSL + `WorkflowRunner`) |
+| Checkpoint Persistence | LangGraph Checkpoint | **implemented** (`StateStore`) |
+| Multi-agent Coordination | CrewAI / LangGraph | **implemented** (`Agent`, handoff) |
+| Conversation Memory | LangChain Memory, mem0 | **implemented** (`Memory`) |
+| Human-in-the-Loop | LangGraph interrupt | **implemented** (`wait_state` + `send_event`) |
+| Observability / Tracing | LangSmith, Langfuse | **implemented** (`Tracer`, Langfuse) |
+
+---
+
+## 3. Design Principles
+
+### 3.1 Ruby-Idiom First
+
+Rather than a direct translation of Python frameworks, this framework is redesigned to align with Ruby's idiomatic expressions, DSL culture, and type system. Instead of Pythonic `@decorator` patterns, it uses Ruby's `include`, `define_method`, blocks/Procs, and module mixins to provide equivalent functionality.
+
+### 3.2 Progressive Adoption
+
+- **Level 0**: Simple chat and tool calls where RubyLLM alone is sufficient
+- **Level 1**: Compose prompt → LLM → parser pipelines with Phronomy's Chain
+- **Level 2**: Define multi-step workflows and agent loops with Workflow
+- **Level 3**: Add state persistence and suspend/resume with Memory/StateStore
+- **Level 4**: Coordinate multiple agents with Multi-agent
+
+Each level can be adopted independently, so there is no need to introduce the entire framework at once.
+
+### 3.3 Rails Integration as First Class
+
+Like RubyLLM, Phronomy ships with a `railtie` and provides `acts_as_*` DSL for ActiveRecord model integration. The cost of embedding it into a Rails app is minimized.
+
+### 3.4 Replaceable LLM Abstraction Layer
+
+RubyLLM serves as the standard backend, but an interface is defined so that other LLM clients can be plugged in as extension points.
+
+### 3.5 Minimal Dependencies
+
+The core depends only on RubyLLM and the Ruby standard library. Optional features (Redis checkpointer, vector search, Observer integration) are separated as optional gems.
+
+---
+
+## 4. Scope
+
+### 4.1 What This Framework Provides
+
+- **Chain**: A composable pipeline of prompt template → LLM → output parser
+- **Agent**: A reusable execution unit with tools, instructions, and LLM settings
+- **Workflow**: A state-based agent workflow defined via a statechart DSL (`Phronomy::Workflow`)
+- **Memory**: Conversation history management (short-term and long-term), context window management
+- **StateStore**: Persistence, suspension, and resumption of workflow execution state
+- **Tool**: Function definitions callable from LLM (extends RubyLLM's Tool)
+- **Guardrail**: Input/output validation and constraints
+- **Tracer**: Execution trace collection and output
+
+### 4.2 What This Framework Does Not Provide (Out of Scope)
+
+- LLM provider API implementations (delegated to RubyLLM)
+- Vector DB implementations (provided externally via adapters)
+- Frontend UI / Chat UI
+- RAG index construction pipelines (usable as tools)
+- Model fine-tuning
+
+---
+
+## 5. Referenced OSS and Their Role
+
+| OSS | Concepts Referenced | Corresponding Component |
+|---|---|---|
+| LangChain Core | Runnable / LCEL chain composition | Chain component |
+| LangGraph | StateGraph, Pregel execution, Checkpoint | `Workflow` DSL / `WorkflowRunner` / `StateStore` components |
+| CrewAI | Agent role-separation model (Crew/Task dropped; Agent-as-Tool adopted instead) | Agent component |
+| OpenAI Agents SDK | Handoff, Guardrail, Tracing | Handoff / Guardrail / Tracer |
+| RubyLLM | LLM abstraction, Tool, Rails integration | Used as the LLM abstraction layer |
+| mem0 | Multi-level memory design | Reference for Memory component design |
+
+---
+
+## 6. Target Users
+
+| User Group | Use Case |
+|---|---|
+| Rails developers | Add AI agent features to existing Rails applications |
+| Ruby backend engineers | Automate AI workflows in batch processing or API services |
+| AI application developers | Build LLM applications in Ruby as a Python alternative |
+
+---
+
+## 7. Name Candidates
+
+| Candidate | Origin / Intent |
+|---|---|
+| **Phronomy** | Agent + workflow/graph flow. Intuitive |
+| **Raix** | Ruby AI eXecution. Short and memorable |
+| **Flowable** | Emphasizes flow/graph composition. Ruby-style `-able` |
+| **Kenna** | Ruby-inspired name |
+
+This document uses **Phronomy** as the working name.
+
+---
+
+*Reference documents: AI Agent Design Guide Part I (00-preface, 01-overview, 02-scope)*

data/docs/archive/design/historical/01_rubyllm_evaluation.md

@@ -0,0 +1,178 @@
+> **HISTORICAL / non-normative snapshot**
+>
+> Preserved as design history. This document does not define current Phronomy
+> architecture or public compatibility. Start at
+> [docs/architecture.md](../../../architecture.md) and the
+> [ADR index](../../../decisions/README.md).
+
+# RubyLLM Evaluation Report — Adoption Assessment as Phronomy Backend
+
+## 1. Overview
+
+This document evaluates the pros and cons of adopting the `ruby_llm` gem as the LLM abstraction layer for Phronomy. LangChain Core (Python) and LiteLLM (Python) are referenced as comparison targets.
+
+---
+
+## 2. Current Capabilities of RubyLLM
+
+Features provided by RubyLLM as of the current state (May 2026).
+
+| Feature | Status | Notes |
+|---|---|---|
+| Multi-provider support | ✅ | OpenAI, Anthropic, Gemini, Bedrock, Azure, Ollama, Mistral, DeepSeek, etc. 13+ |
+| Chat API | ✅ | `RubyLLM.chat` |
+| Tool calling (Function Calling) | ✅ | `RubyLLM::Tool` DSL |
+| Agent DSL | ✅ | `RubyLLM::Agent` class-based |
+| Streaming | ✅ | SSE-based |
+| Embeddings | ✅ | `RubyLLM.embed` |
+| Image generation | ✅ | `RubyLLM.paint` |
+| Audio transcription | ✅ | `RubyLLM.transcribe` |
+| Moderation | ✅ | `RubyLLM.moderate` |
+| Structured output | ✅ | Via `ruby_llm-schema` gem |
+| Extended Thinking | ✅ | `thinking.rb` |
+| Rails / ActiveRecord integration | ✅ | `acts_as_chat`, `acts_as_message` |
+| Rails generators | ✅ | install, agent, tool, chat UI, etc. |
+| Model registry | ✅ | 800+ models, capability/pricing information |
+| Async support | ✅ | Asynchronous execution |
+| Multimodal | ✅ | Image, audio, PDF attachments |
+
+RubyLLM covers nearly all the functionality needed as an "LLM abstraction layer" and has rich Rails integration.
+
+---
+
+## 3. Evaluation from the Phronomy Perspective
+
+### 3.1 Advantages
+
+#### (A) High completeness as an LLM abstraction layer
+
+Provider differences (API specs, authentication, streaming, tool calling formats) are already handled, so Phronomy development does not need to build the LLM communication layer from scratch. Support for 13+ providers is extremely important in production.
+
+#### (B) Tool definitions are easy to use as a Ruby DSL
+
+```ruby
+class WebSearch < RubyLLM::Tool
+  description "Searches the web for information"
+  
+  param :query, type: :string, desc: "The search query"
+  param :max_results, type: :integer, desc: "Maximum results", required: false
+  
+  def execute(query:, max_results: 5)
+    # implementation
+  end
+end
+```
+
+Phronomy's Tool component can be designed to inherit and extend this DSL.
+
+#### (C) Affinity with Rails / ActiveRecord
+
+`acts_as_chat` and `acts_as_message` allow DB persistence of conversation history directly. Useful as the foundation for Phronomy's `StateStore::ActiveRecord` implementation.
+
+#### (D) Built-in model registry
+
+Model capabilities (whether function calling is supported, vision support, etc.) can be retrieved from the registry. Useful when Phronomy makes "dynamic decisions based on the capabilities of the model in use."
+
+#### (E) Minimal dependencies with low security risk
+
+Main dependencies are only `faraday` (HTTP) and `event_stream_parser` (SSE). Compared to frameworks with many dependencies, the security supply-chain risk is small.
+
+#### (F) Commitment to the Ruby ecosystem
+
+The combination of Rails generators, `railtie.rb`, and `acts_as_*` DSL shows strong commitment to the Ruby/Rails community. Phronomy can inherit the same culture.
+
+#### (G) Streaming support is built-in
+
+SSE-based streaming is implemented as standard, so Phronomy's streaming UX features (progressive token display) can be used at no additional cost.
+
+---
+
+### 3.2 Disadvantages and Limitations
+
+#### (A) Agent orchestration features are too basic
+
+`RubyLLM::Agent` can declare model/instructions/tools/temperature to run a single agent, but does not support:
+
+- **State graph**: Workflow execution defining multiple steps with states and transitions
+- **Checkpoint**: Suspend/resume of graph state (ActiveRecord persistence exists, but not AgentLoop state saving)
+- **Multi-agent coordination**: Agent-to-agent handoff / delegation
+- **Human-in-the-Loop**: Mechanism to pause execution and wait for user approval
+
+→ **Mitigation**: Phronomy implements these as an upper layer. RubyLLM's Agent is positioned internally as an "execution node for LLM calls."
+
+#### (B) No context management or conversation compression
+
+Chat accumulates conversation history, but there is no context compression, summarization, or deletion policy against token limits. Context window overflow occurs in long agent loops.
+
+→ **Mitigation**: Phronomy's `Memory` / `ContextManager` components provide conversation compression, summaries, and sliding windows.
+
+#### (C) No chain composition (pipeline) mechanism
+
+There is no mechanism for chain composition via `|` operator like LCEL (LangChain Expression Language), or for defining pipelines of prompt template → LLM → output parser.
+
+→ **Mitigation**: Phronomy's `Chain` component provides pipeline composition via `>>` operator (or `|`).
+
+#### (D) Limited output parsers
+
+Structured output via `ruby_llm-schema` exists, but there is no flexible output formatting/transformation layer equivalent to LangChain's diverse `OutputParser` (JSON, XML, Markdown, Pydantic, etc.).
+
+→ **Mitigation**: Phronomy's `OutputParser` component provides various parsers.
+
+#### (E) No observability or tracing
+
+No execution trace collection or output to LangSmith or Langfuse. Lacks the debugging/monitoring infrastructure needed in production.
+
+→ **Mitigation**: Phronomy's `Tracer` component provides OpenTelemetry-based tracing.
+
+#### (F) Community and ecosystem are small compared to Python
+
+No massive plugin ecosystem or integration library collection like LangChain or CrewAI. Third-party Tool/Integration beyond provider integration is limited.
+
+→ **Mitigation**: Phronomy implements MCP (Model Context Protocol) support so that Python's MCP tool ecosystem can be used from Ruby.
+
+#### (G) No Pregel/Workflow runtime
+
+There is no Ruby implementation equivalent to LangGraph's core Pregel computation model (workflow state scheduling, parallel execution, channel-based value propagation).
+
+→ **Mitigation**: Phronomy implements a lightweight Pregel-like graph runtime (simple version initially, extended later).
+
+#### (H) Integration with Ruby's async processing ecosystem
+
+Ruby's async processing (Async gem, Fiber-based) is still developing compared to Python's asyncio. Async execution design in Phronomy requires careful judgment.
+
+→ **Mitigation**: Support synchronous execution fully first, then provide async incrementally with Fiber/Thread.
+
+---
+
+## 4. Adoption Decision
+
+### 4.1 Reasons for Adopting (Recommended)
+
+RubyLLM covers all necessary functionality as an "LLM abstraction layer" and has made significant investment in the Ruby/Rails ecosystem. By implementing the missing "framework layer" (graph execution, chain composition, memory management) as an upper layer, a collaborative design that leverages each other's strengths is possible.
+
+### 4.2 Alternatives if Not Adopted
+
+| Alternative | Issues |
+|---|---|
+| Implement from scratch with direct Faraday | Enormous implementation cost for provider support |
+| Langchainrb gem | Maintenance status unstable, limited features |
+| Call Python LangChain via Ruby FFI | Loses Ruby idiom, deployment complexity |
+| OpenAI Ruby gem alone | Locked to OpenAI, no multi-provider |
+
+### 4.3 Adoption Form
+
+- **Core dependency**: Require `ruby_llm` as a mandatory dependency
+- **Extension point**: Define a `Phronomy::LLM::Base` interface so adapters for non-RubyLLM clients can be connected in the future
+- **Tool inheritance**: `Phronomy::Tool` inherits (or delegates to) `RubyLLM::Tool` to provide additional functionality
+- **Agent usage**: Use `RubyLLM::Agent` internally while wrapping it as a Phronomy Workflow node
+
+---
+
+## 5. Version Requirements
+
+```ruby
+# Gemfile
+gem 'ruby_llm', '>= 1.3'   # After Tool DSL, Agent, Streaming, Rails integration stabilized
+```
+
+---

data/docs/archive/design/historical/06_design_decisions.md

@@ -0,0 +1,143 @@
+> **HISTORICAL / non-normative snapshot**
+>
+> Preserved as design history. This document does not define current Phronomy
+> architecture or public compatibility. Start at
+> [docs/architecture.md](../../../architecture.md) and the
+> [ADR index](../../../decisions/README.md).
+
+# Phronomy — Design Decision Log
+
+A record of design decisions and their rationale. Use this as a reference when revisiting decisions later.
+
+---
+
+## Decision 1: Adopt RubyLLM as the LLM abstraction layer
+
+**Situation**: Needed to choose between a custom implementation and RubyLLM as the backend for Phronomy.
+
+**Choice**: Adopt RubyLLM.
+
+**Rationale**:
+- Provider support is already implemented, reducing Phronomy's development cost.
+- Rails/ActiveRecord integration, streaming, and model registry cover foundations Phronomy needs.
+- Natural Ruby DSL code aligns well with Phronomy's DSL.
+- Focusing on Agent/Workflow semantics provides better return than rebuilding provider clients.
+
+**Trade-offs**:
+- RubyLLM API changes must be tracked.
+- Providers outside RubyLLM may lag.
+- `Phronomy::LLMAdapter::Base` keeps the provider boundary replaceable.
+
+---
+
+## Decision 2: Manage state as immutable objects
+
+**Situation**: Needed to choose between mutable hashes and immutable objects for Workflow state management.
+
+**Choice**: `State#merge` immutably returns a new object.
+
+**Rationale**:
+- Checkpoint saving and comparison are easier.
+- Accidental cross-node mutation is reduced.
+- History tracking and debugging are clearer.
+- Parallel logical execution has fewer shared-mutation hazards.
+
+**Trade-offs**:
+- State updates copy objects.
+- Initial implementation favors shallow immutable transitions over deep-copy complexity.
+
+---
+
+## Decision 3: Use `>>` operator for Chain composition (`|` as alias)
+
+**Situation**: Needed a Ruby composition syntax inspired by LCEL.
+
+**Choice**: `>>` is primary and `|` remains an alias.
+
+**Rationale**:
+- `>>` is consistent with Ruby `Proc#>>` function composition.
+- `|` remains familiar to LangChain users.
+
+---
+
+## Decision 4: Implement the Workflow graph runtime in-house
+
+**Situation**: General graph gems do not model stateful Agent execution, checkpoints, suspension, or events well.
+
+**Choice**: Maintain the specialized Workflow/FSM execution engine in Phronomy.
+
+**Rationale**:
+- Agent lifecycle semantics are more important than general graph algorithms.
+- Explicit state/event behavior integrates directly with persistence and suspension.
+
+**Trade-offs**:
+- Runtime correctness remains a framework responsibility.
+
+---
+
+## Decision 5: Unify memory scope by thread
+
+**Situation**: Needed a simple durable context scope before adding multi-level memory.
+
+**Choice**: Use `thread_id` as the primary conversation/session scope.
+
+**Rationale**:
+- It covers the common conversation lifecycle.
+- Applications may map domain identities such as user IDs onto thread IDs.
+
+---
+
+## Decision 6: Security — Tool execution is no-sandbox by default
+
+**Situation**: Process sandboxing would add deployment-specific dependencies to the core framework.
+
+**Choice**: No sandbox by default. Use approval policy, guardrails, and application-owned deployment isolation.
+
+**Risk mitigation**:
+- Irreversible operations should require approval.
+- Shell/process capabilities are application-defined rather than implicitly enabled.
+
+---
+
+## Decision 7: EventLoop/FSMSession owns lifecycle; OffloadPool owns synchronous offload
+
+**Situation**: Phronomy needs many concurrently waiting Agent, Workflow, Tool,
+and MultiAgent lifecycles without one OS Thread per logical task. It also needs a
+bounded place for synchronous work that must not block EventLoop.
+
+**Choice**: Framework lifecycle coordination uses one Runtime-owned EventLoop and
+explicit FSMSession state/events. `Phronomy::Task` is only a completion handle.
+Synchronous work that cannot safely run on EventLoop uses the bounded
+`OffloadPool`.
+
+Tool execution classification is deliberately limited to:
+
+```text
+:cooperative
+:offloaded
+```
+
+The application decides whether work is safe on EventLoop. The framework does
+not separately classify I/O-bound, CPU-bound, or process work. Blocking I/O,
+CPU-bound synchronous Ruby work, and other long synchronous calls may all use
+`:offloaded`.
+
+**Rationale**:
+- Waiting for another Agent, approval, timer, or event does not require an OS Thread.
+- Agent/Workflow/Tool/MultiAgent share one explicit continuation model.
+- The distinction Phronomy must enforce is EventLoop-safe versus off-EventLoop, not I/O versus CPU.
+- A bounded shared OffloadPool provides backpressure without inventing a separate executor taxonomy prematurely.
+- Named pools allow applications to isolate workloads when shared capacity is insufficient.
+
+**Trade-offs**:
+- FSM actions must return promptly and explicitly model later completion events.
+- Applications own `offload_pool_size`, queue sizing, and workload-mix capacity planning.
+- Thread offload does not provide CPU isolation, remove CRuby GVL contention, or guarantee I/O/CPU fairness.
+- A future subprocess offload facility may add stronger CPU/process isolation without changing the Tool execution-mode contract.
+- Synchronous public wrappers must not be called from the EventLoop thread.
+
+See ADR-010 for the authoritative current concurrency model.
+
+---
+
+*References: 00_design_philosophy.md, 01_rubyllm_evaluation.md, AI Agent Design Guide 02-scope.md*

data/docs/changelog/0.14-and-earlier.md

@@ -815,7 +815,7 @@ current at the time of each release.
 ### Maintenance
 
 - **Archive stale Rails integration design doc** (#91): Added an archived
-  notice to `spec/design/17_rails_integration.md` clarifying that Rails
+  notice to `docs/archive/design/archived/17_rails_integration.md` clarifying that Rails
   integration was removed in v0.3.0–v0.5.1 and the document is for
   historical reference only.
 

data/docs/decisions/001-rubyllm-as-provider-layer.md

@@ -2,7 +2,12 @@
 
 ## Status
 
-Accepted
+Superseded
+
+Superseded by
+[`027-llm-adapter-provider-boundary`](027-llm-adapter-provider-boundary.md).
+The historical rationale for adopting RubyLLM is preserved below; the direct
+Provider-call boundary described by this ADR is no longer normative.
 
 ## Context
 

data/docs/decisions/002-workflow-context-immutability.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-Accepted
+Amended
 
 ## Context
 
@@ -40,3 +40,28 @@ object. The framework replaces the current state with the returned value.
 - Node authors must remember to return the new state; forgetting to do so
   discards the update silently. (Future work: frozen state objects or
   a strict return type could catch this at dev time.)
+
+## Amendment — EventLoop-owned direct field mutation
+
+The original Decision remains normative for `WorkflowContext#merge`, but its
+statement that **all field writers** return a new `WorkflowContext` is amended.
+
+Current semantics are:
+
+1. `WorkflowContext#merge` remains a non-mutating, new-instance operation. It
+   applies each field's merge policy and returns a replacement
+   `WorkflowContext`.
+2. Direct generated field writers are controlled mutation APIs. They update the
+   current `WorkflowContext` instance only when code is executing under
+   Phronomy's Runtime/EventLoop write authority.
+3. A direct field write outside EventLoop dispatch authority fails with
+   `Phronomy::WorkflowContextOwnershipError`.
+4. EventLoop write authority and Ruby object immutability are distinct
+   state-management concerns. The single-writer rule does not require every live
+   state transition to allocate a replacement Ruby object.
+5. This amendment does not introduce or redefine Workflow identity. Durable
+   Workflow identity remains `workflow_instance_id`.
+
+The original rationale for value-style `merge` remains useful: application code
+can construct replacement state without mutating the source context, while
+Runtime-owned event processing may use guarded direct writers when appropriate.

data/docs/decisions/006-no-built-in-guardrails.md

@@ -2,7 +2,8 @@
 
 ## Status
 
-Amended (see Amendment section below)
+Superseded by
+[ADR-019: Filter Contract and Security Boundaries](019-filter-contract-and-security-boundaries.md).
 
 ## Context