phronomy 0.2.2 → 0.4.0

data/lib/phronomy/workflow_runner.rb

@@ -38,7 +38,7 @@ module Phronomy
 
     def initialize(state_class:, nodes:, after_transitions:, route_transitions:,
       external_events:, entry_point:, wait_state_names: [],
-      before_callbacks: {}, after_callbacks: {}, state_store: nil)
+      before_callbacks: {}, after_callbacks: {})
       @state_class = state_class
       @nodes = nodes
       @after_transitions = after_transitions  # { from => to }
@@ -48,7 +48,6 @@ module Phronomy
       @wait_state_names = wait_state_names
       @before_callbacks = before_callbacks.dup
       @after_callbacks = after_callbacks.dup
-      @state_store_override = state_store
       @phase_machine_class = build_phase_machine_class
     end
 
@@ -134,29 +133,46 @@ module Phronomy
 
     private
 
-    def state_store
-      @state_store_override || Phronomy.configuration.default_state_store
-    end
-
     def run_graph(state, from_node: nil, recursion_limit: 25, &event_block)
       current_node = from_node || @entry_point
       tracker = new_phase_machine(current_node)
       tracker.context = state
+      # Event queue: decouple node execution from transition firing.
+      # Events are enqueued after a node completes and processed at the top
+      # of the next iteration so that guards always see the freshest context.
+      event_queue = []
       step = 0
 
-      while current_node && current_node != FINISH
-        if step >= recursion_limit
-          raise Phronomy::RecursionLimitError,
-            "Recursion limit (#{recursion_limit}) exceeded"
+      loop do
+        break if current_node == FINISH
+
+        # -- Process next pending event -----------------------------------------
+        # Dequeue one event and fire it against the state machine. Guards are
+        # evaluated here (at fire time) so they see the context written by the
+        # node that enqueued the event.
+        if (event = event_queue.shift)
+          if step >= recursion_limit
+            raise Phronomy::RecursionLimitError,
+              "Recursion limit (#{recursion_limit}) exceeded"
+          end
+
+          fire_event!(tracker, event, current_node)
+          next_phase = tracker.phase.to_sym
+          # When next_phase == current_node no transition matched → terminal node.
+          current_node = (next_phase == current_node) ? FINISH : next_phase
+          step += 1
+          next
         end
 
-        # Auto-halt at wait states: save context and return to caller.
+        # -- Queue empty: check for halt -----------------------------------------
+        # Auto-halt at wait states: persist phase in context and return to caller.
+        # The caller resumes via send_event, which starts a fresh run_graph call.
         if @wait_state_names.include?(current_node)
           state.set_graph_metadata(thread_id: state.thread_id, phase: current_node)
-          state_store&.save(state)
           return state
         end
 
+        # -- Execute node action ------------------------------------------------
         node_fn = @nodes[current_node]
         raise ArgumentError, "Node #{current_node.inspect} is not defined" unless node_fn
 
@@ -171,31 +187,25 @@ module Phronomy
             "expected Hash, #{@state_class}, or nil"
         end
 
-        # Update tracker so guards see the freshest context.
+        # Update tracker so guards see the freshest context when the event fires.
         tracker.context = state
 
         event_block&.call({node: current_node, state: state})
 
-        # Delegate transition decision to state_machines.
+        # -- Enqueue transition event -------------------------------------------
+        # node_completed: generic event for all after-transitions (unconditional).
+        # route event:    user-named event carrying guarded conditional branches.
+        # No enqueue:     terminal node — next iteration exits via FINISH check.
         if @after_transitions.key?(current_node)
-          fire_event!(tracker, :"advance_#{current_node}", current_node)
+          event_queue << :node_completed
         elsif @route_transitions.key?(current_node)
-          ev_name = @route_transitions[current_node][:event_name]
-          fire_event!(tracker, ev_name, current_node)
+          event_queue << @route_transitions[current_node][:event_name]
+        else
+          current_node = FINISH
         end
-        # Nodes with no declared outgoing transition are treated as terminal:
-        # next_phase == current_node triggers the FINISH assignment below.
-
-        next_phase = tracker.phase.to_sym
-        # When next_phase == current_node: no transition fired (terminal node) → end.
-        # When next_phase == :__end__ (== FINISH): route led to finish → exit loop.
-        current_node = (next_phase == current_node) ? FINISH : next_phase
-
-        step += 1
       end
 
       state.set_graph_metadata(thread_id: state.thread_id, phase: :__end__)
-      state_store&.save(state)
       state
     end
 
@@ -232,9 +242,11 @@ module Phronomy
         state_machine :phase, initial: entry do
           all_states.each { |s| state s }
 
-          # 1. After-transitions: unconditional, fire on action completion.
-          after_trans.each do |from, to|
-            event :"advance_#{from}" do
+          # 1. After-transitions: one generic :node_completed event covers all
+          #    unconditional transitions. This keeps event names independent of
+          #    source state names and matches standard state machine semantics.
+          event :node_completed do
+            after_trans.each do |from, to|
               transition from => to
             end
           end

data/lib/phronomy.rb

@@ -2,6 +2,7 @@
 
 require "zeitwerk"
 require "ruby_llm"
+require_relative "phronomy/ruby_llm_patches"
 
 loader = Zeitwerk::Loader.for_gem
 loader.ignore(File.expand_path("generators", __dir__))
@@ -26,6 +27,23 @@ module Phronomy
 
   class HandoffError < Error; end
 
+  # Raised by {Phronomy::GeneratorVerifier#invoke} when +raise_if_untrusted: true+
+  # and the pipeline's combined confidence score falls below the configured threshold.
+  #
+  # @example
+  #   rescue Phronomy::LowConfidenceError => e
+  #     puts e.result.confidence   # => e.g. 0.45
+  #     puts e.result.output       # best-effort answer despite low confidence
+  class LowConfidenceError < Error
+    # @return [Phronomy::GeneratorVerifier::Result] the untrusted result
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super("Answer confidence #{result.confidence} is below the required threshold")
+    end
+  end
+
   class GuardrailError < Error
     attr_reader :guardrail
 

data/scripts/check_readme_ruby.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Extracts every ```ruby ... ``` block from README.md and runs `ruby -c` on each.
+# Exits non-zero if any block has a syntax error.
+
+require "tempfile"
+require "open3"
+
+readme_path = File.expand_path("../README.md", __dir__)
+readme = File.read(readme_path)
+blocks = readme.scan(/^```ruby\n(.*?)^```/m).map.with_index(1) { |(code), i| [i, code] }
+
+puts "Checking #{blocks.size} Ruby code blocks in README.md..."
+
+failures = []
+
+blocks.each do |index, code|
+  Tempfile.create(["readme_block_#{index}", ".rb"]) do |f|
+    f.write(code)
+    f.flush
+    stdout, status = Open3.capture2e("ruby", "-c", f.path)
+    if status.success?
+      puts "  OK   block ##{index}"
+    else
+      failures << index
+      puts "  FAIL block ##{index}"
+      puts stdout.gsub(f.path, "block ##{index}")
+    end
+  end
+end
+
+if failures.empty?
+  puts "All #{blocks.size} Ruby code blocks passed syntax check."
+  exit 0
+else
+  puts "\n#{failures.size} block(s) failed syntax check: #{failures.join(", ")}"
+  exit 1
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-17 00:00:00.000000000 Z
+date: 2026-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -52,9 +52,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
-description: Phronomy provides Agent, Workflow, Memory, Tool, Guardrail, RAG, and
-  Multi-agent capabilities for building AI agents in Ruby and Rails. Powered by RubyLLM
-  for LLM abstraction.
+description: Phronomy provides Agent, Workflow, Tool, Guardrail, RAG, and Multi-agent
+  capabilities for building AI agents in Ruby. Powered by RubyLLM for LLM abstraction.
 email:
 - raizo.tcs@gmail.com
 executables: []
@@ -65,23 +64,22 @@ files:
 - CHANGELOG.md
 - README.md
 - Rakefile
-- docs/trustworthy_ai_enhancements.md
 - lib/generators/phronomy/install/install_generator.rb
 - lib/generators/phronomy/install/templates/create_phronomy_messages.rb.tt
 - lib/generators/phronomy/install/templates/initializer.rb.tt
 - lib/generators/phronomy/install/templates/message_model.rb.tt
 - lib/phronomy.rb
-- lib/phronomy/active_record/acts_as.rb
-- lib/phronomy/active_record/checkpoint.rb
-- lib/phronomy/active_record/extensions.rb
-- lib/phronomy/active_record/message.rb
-- lib/phronomy/actor.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
+- lib/phronomy/agent/checkpoint.rb
 - lib/phronomy/agent/handoff.rb
+- lib/phronomy/agent/orchestrator.rb
 - lib/phronomy/agent/react_agent.rb
 - lib/phronomy/agent/runner.rb
+- lib/phronomy/agent/shared_state.rb
+- lib/phronomy/agent/suspend_signal.rb
+- lib/phronomy/agent/team_coordinator.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
 - lib/phronomy/context/assembler.rb
@@ -107,6 +105,7 @@ files:
 - lib/phronomy/eval/scorer/exact_match.rb
 - lib/phronomy/eval/scorer/includes_scorer.rb
 - lib/phronomy/eval/scorer/llm_judge.rb
+- lib/phronomy/generator_verifier.rb
 - lib/phronomy/guardrail.rb
 - lib/phronomy/guardrail/base.rb
 - lib/phronomy/guardrail/builtin.rb
@@ -124,43 +123,18 @@ files:
 - lib/phronomy/loader/csv_loader.rb
 - lib/phronomy/loader/markdown_loader.rb
 - lib/phronomy/loader/plain_text_loader.rb
-- lib/phronomy/memory.rb
-- lib/phronomy/memory/compression.rb
-- lib/phronomy/memory/compression/base.rb
-- lib/phronomy/memory/compression/summary.rb
-- lib/phronomy/memory/compression/tool_output_pruner.rb
-- lib/phronomy/memory/conversation_manager.rb
-- lib/phronomy/memory/retrieval.rb
-- lib/phronomy/memory/retrieval/base.rb
-- lib/phronomy/memory/retrieval/composite.rb
-- lib/phronomy/memory/retrieval/recent.rb
-- lib/phronomy/memory/retrieval/semantic.rb
-- lib/phronomy/memory/storage.rb
-- lib/phronomy/memory/storage/active_record.rb
-- lib/phronomy/memory/storage/base.rb
-- lib/phronomy/memory/storage/in_memory.rb
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
 - lib/phronomy/output_parser/structured_parser.rb
 - lib/phronomy/prompt_template.rb
-- lib/phronomy/rails/agent_job.rb
 - lib/phronomy/railtie.rb
+- lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
 - lib/phronomy/splitter.rb
 - lib/phronomy/splitter/base.rb
 - lib/phronomy/splitter/fixed_size_splitter.rb
 - lib/phronomy/splitter/recursive_splitter.rb
-- lib/phronomy/state_store.rb
-- lib/phronomy/state_store/active_record.rb
-- lib/phronomy/state_store/base.rb
-- lib/phronomy/state_store/encryptor.rb
-- lib/phronomy/state_store/encryptor/active_support.rb
-- lib/phronomy/state_store/encryptor/base.rb
-- lib/phronomy/state_store/file.rb
-- lib/phronomy/state_store/in_memory.rb
-- lib/phronomy/state_store/redis.rb
-- lib/phronomy/thread_actor_registry.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/agent_tool.rb
@@ -171,7 +145,6 @@ files:
 - lib/phronomy/tracing/langfuse_tracer.rb
 - lib/phronomy/tracing/null_tracer.rb
 - lib/phronomy/tracing/open_telemetry_tracer.rb
-- lib/phronomy/trust_pipeline.rb
 - lib/phronomy/vector_store.rb
 - lib/phronomy/vector_store/base.rb
 - lib/phronomy/vector_store/in_memory.rb
@@ -181,6 +154,7 @@ files:
 - lib/phronomy/workflow.rb
 - lib/phronomy/workflow_context.rb
 - lib/phronomy/workflow_runner.rb
+- scripts/check_readme_ruby.rb
 - sig/phronomy.rbs
 homepage: https://github.com/Raizo-TCS/phronomy
 licenses:

data/docs/trustworthy_ai_enhancements.md

@@ -1,332 +0,0 @@
-# Trustworthy AI Enhancements
-
-Specification for features that address the NIST AI Risk Management Framework (AI RMF 1.0)
-trustworthiness characteristics, as applied to the phronomy gem.
-
-Reference: NIST AI 100-1 — https://doi.org/10.6028/NIST.AI.100-1
-Japanese translation: https://aisi.go.jp/assets/pdf/NIST_AI_RMF_jp_20240806.pdf
-
----
-
-## Responsibility Model
-
-Three layers share responsibility for trustworthy AI:
-
-```
-┌─────────────────────────────────────────┐
-│  Application  Domain logic / UX          │
-├─────────────────────────────────────────┤
-│  phronomy     Control flow / observation / boundary enforcement │
-├─────────────────────────────────────────┤
-│  LLM          Probabilistic reasoning / generation              │
-└─────────────────────────────────────────┘
-```
-
-Key principle: **the LLM is untrusted**. phronomy acts as the deterministic control
-layer that validates, constrains, and observes LLM behaviour. Characteristics that
-cannot be delegated to the LLM must be enforced by phronomy or the application layer.
-
----
-
-## Trustworthiness Characteristics — Status and Plan
-
-### 3.1 Valid and Reliable
-
-| Layer | Responsibility | Status |
-|---|---|---|
-| LLM | Base reasoning capability | Model-dependent |
-| **phronomy** | Eval infrastructure, output type validation | ✅ `Eval::Runner`, `Eval::Dataset`, `Eval::Metrics` — see `lib/phronomy/eval/` |
-| **phronomy** | Drift / accuracy monitoring hooks | ❌ Not implemented — **planned** |
-| Application | Test-case design, accuracy thresholds | Application responsibility |
-
-**Planned work:**
-- None in this iteration. `Eval` infrastructure is sufficient for current needs.
-
----
-
-### 3.2 Safe
-
-| Layer | Responsibility | Status |
-|---|---|---|
-| LLM | Basic harmful-content avoidance (RLHF) | Model-dependent, not guaranteed |
-| **phronomy** | Intervention points, iteration limits, approval gates | ✅ `wait_state`/`send_event`, `requires_approval`, `max_iterations` — see `lib/phronomy/workflow.rb`, `lib/phronomy/agent/base.rb` |
-| **phronomy** | Built-in guardrails (PII, prompt injection) | ❌ Not implemented — **planned (Feature A)** |
-| Application | Concrete guardrail logic, approval workflows | Application responsibility |
-
----
-
-### 3.3 Secure and Resilient
-
-| Layer | Responsibility | Status |
-|---|---|---|
-| LLM | Partial prompt-injection resistance | Model-dependent, partial |
-| **phronomy** | State persistence across process restarts | ✅ `StateStore::ActiveRecord` — see `lib/phronomy/state_store/` |
-| **phronomy** | Encrypted state store adapter interface | ❌ Not implemented — **planned (Feature C)** |
-| Application | Authentication / authorisation / infrastructure encryption | Application / infrastructure responsibility |
-
----
-
-### 3.4 Accountable and Transparent
-
-| Layer | Responsibility | Status |
-|---|---|---|
-| LLM | Token usage reporting | ✅ `TokenUsage` — see `lib/phronomy/token_usage.rb` |
-| **phronomy** | Tracing / span recording | ✅ `Tracing::LangfuseTracer`, `OpenTelemetryTracer` — see `lib/phronomy/tracing/` |
-| **phronomy** | Caller identity propagation to tracers | ❌ Not implemented — **planned (Feature B)** |
-| Application | User-facing AI disclosure, business audit requirements | Application responsibility |
-
----
-
-### 3.5 Explainable and Interpretable
-
-| Layer | Responsibility | Status |
-|---|---|---|
-| LLM | Chain-of-thought generation | Prompt-dependent |
-| **phronomy** | Processing step recording via Graph and Tracing | ✅ Partial — `Workflow`/`WorkflowRunner`, `Tracing` |
-| Application | Explanation UI, CoT prompt design | Application responsibility |
-
-**Planned work:** None in this iteration.
-
----
-
-### 3.6 Privacy-Enhanced
-
-| Layer | Responsibility | Status |
-|---|---|---|
-| LLM | Training data handling | Provider responsibility |
-| **phronomy** | Memory compression (data minimisation) | ✅ `Memory::Compression` — see `lib/phronomy/memory/compression/` |
-| **phronomy** | Built-in PII detection guardrail | ❌ Not implemented — **planned (Feature A)** |
-| **phronomy** | TTL and explicit purge API on ConversationManager | ❌ Not implemented — **planned (Feature D)** |
-| Application | Privacy policy, user consent management | Application responsibility |
-
----
-
-### 3.7 Fair — with Harmful Bias Managed
-
-| Layer | Responsibility | Status |
-|---|---|---|
-| LLM | Bias reduction via RLHF | Provider responsibility |
-| **phronomy** | Eval infrastructure for custom metrics | ✅ `Eval::Metrics` — extensible |
-| Application | Fairness test-set design, threshold definition | Application responsibility |
-
-**Planned work:** None in this iteration. The existing `Eval::Metrics` extension
-point is sufficient; fairness metrics are domain-specific and belong to the
-application layer.
-
----
-
-## Planned Features (This Branch)
-
-### Feature A — `Phronomy::Guardrail::Builtin` module
-
-**Addresses:** 3.2 Safe, 3.6 Privacy-Enhanced
-
-**Motivation:**
-Prompt injection and PII leakage are the two most common, high-severity risks for
-any LLM application. They require deterministic, regex/heuristic-based detection
-that the LLM cannot reliably provide. phronomy should ship sensible defaults so
-that applications do not have to re-implement these from scratch.
-
-**Design:**
-- New module: `Phronomy::Guardrail::Builtin`
-- Two concrete classes, both under `lib/phronomy/guardrail/builtin/`:
-  - `PromptInjectionDetector < InputGuardrail`
-  - `PIIPatternDetector < InputGuardrail`
-- Existing base classes (`InputGuardrail`, `OutputGuardrail`) are unchanged — see
-  `lib/phronomy/guardrail/input_guardrail.rb` and `output_guardrail.rb`.
-
-**`PromptInjectionDetector`:**
-- Detects common prompt-injection patterns in input strings:
-  - "ignore previous instructions", "disregard all prior", "system prompt:" prefixes,
-    jailbreak keywords, role-switch attempts.
-- Pattern list is configurable via constructor argument `additional_patterns: []`.
-- Raises `GuardrailError` with message `"Potential prompt injection detected"`.
-
-**`PIIPatternDetector`:**
-- Detects common Japanese and international PII patterns:
-  - Japanese My Number (12-digit number): `/\b\d{4}[- ]?\d{4}[- ]?\d{4}\b/`
-  - Credit card numbers: `/\b(?:\d{4}[- ]?){3}\d{4}\b/`
-  - Email addresses: standard RFC 5322 simplified pattern
-  - Phone numbers (JP): `/\b0\d{1,4}[- ]?\d{1,4}[- ]?\d{4}\b/`
-- Each pattern category is independently togglable via constructor:
-  `PIIPatternDetector.new(detect: [:my_number, :credit_card, :email, :phone])`
-- Default: all four categories active.
-- Raises `GuardrailError` with message `"PII detected in input: <category>"`.
-
-**Usage example:**
-```ruby
-agent = MyAgent.new
-agent.add_input_guardrail(Phronomy::Guardrail::Builtin::PromptInjectionDetector.new)
-agent.add_input_guardrail(Phronomy::Guardrail::Builtin::PIIPatternDetector.new(detect: [:my_number, :credit_card]))
-```
-
-**Files to create:**
-- `lib/phronomy/guardrail/builtin/prompt_injection_detector.rb`
-- `lib/phronomy/guardrail/builtin/pii_pattern_detector.rb`
-- `lib/phronomy/guardrail/builtin.rb` (requires both, defines module)
-- Update `lib/phronomy/guardrail.rb` to require `builtin`
-
-**Tests:**
-- Unit: `spec/phronomy/guardrail/builtin/prompt_injection_detector_spec.rb`
-- Unit: `spec/phronomy/guardrail/builtin/pii_pattern_detector_spec.rb`
-- Integration: extend `spec/integration/tool_guardrail_spec.rb` with builtin guardrail factors
-
----
-
-### Feature B — Caller identity propagation in `config:`
-
-**Addresses:** 3.4 Accountable and Transparent
-
-**Motivation:**
-`Tracing` already records what happened (spans, token usage). What is missing is
-**who** triggered the action. Without a caller identity, audit logs cannot be
-attributed to users or sessions, which is a requirement for accountability under
-NIST AI RMF 3.4.
-
-**Design:**
-- `Agent::Base#invoke` and `WorkflowRunner#invoke` already accept `config: {}` — see
-  `lib/phronomy/agent/base.rb` and `lib/phronomy/graph/workflow_runner.rb`.
-- Add two new optional keys to `config:`:
-  - `user_id:` (String | nil) — caller identity
-  - `session_id:` (String | nil) — session / request identity
-- Both are extracted in `invoke_once` / `call` and forwarded to
-  `Tracing::Base#start_span` as span attributes.
-- `Tracing::Base#start_span` already accepts `**attributes` — no signature change needed.
-- `LangfuseTracer` and `OpenTelemetryTracer` will automatically forward them as
-  metadata/attributes respectively.
-
-**Usage example:**
-```ruby
-agent.invoke("What is the weather?", config: {
-  thread_id: "conv-123",
-  user_id:   "user-42",
-  session_id: "sess-abc"
-})
-```
-
-**Files to modify:**
-- `lib/phronomy/agent/base.rb` — extract `user_id` and `session_id` from config, pass to tracer
-- `lib/phronomy/graph/compiled_graph.rb` — same for graph invocations
-
-**Tests:**
-- Unit: extend `spec/phronomy/agent_spec.rb` with `user_id`/`session_id` forwarding assertions
-- Unit: extend `spec/phronomy/tracing/langfuse_tracer_spec.rb` with attribute forwarding
-
----
-
-### Feature C — `StateStore` encryption adapter interface
-
-**Addresses:** 3.3 Secure and Resilient
-
-**Motivation:**
-`StateStore::ActiveRecord` persists conversation state as plain-text JSON. In
-regulated environments (healthcare, finance, government) this violates data-at-rest
-requirements. phronomy should define a standard interface so that an encryption
-adapter can be layered transparently without modifying `StateStore::ActiveRecord`.
-
-**Design:**
-- New abstract class: `Phronomy::StateStore::Encryptor::Base`
-  - `encrypt(plaintext) → ciphertext` (abstract)
-  - `decrypt(ciphertext) → plaintext` (abstract)
-- New concrete class: `Phronomy::StateStore::Encryptor::ActiveSupport`
-  - Delegates to `ActiveSupport::MessageEncryptor` when available.
-  - Constructor: `ActiveSupport.new(secret_key_base:, cipher: "aes-256-gcm")`
-- `StateStore::ActiveRecord` accepts an optional `encryptor:` constructor argument:
-  - When present, `serialize_state` output is passed through `encryptor.encrypt`
-    before writing to the DB, and `encryptor.decrypt` before `deserialize_state`.
-  - When absent, behaviour is unchanged (backwards compatible).
-
-**Usage example:**
-```ruby
-encryptor = Phronomy::StateStore::Encryptor::ActiveSupport.new(
-  secret_key_base: ENV.fetch("SECRET_KEY_BASE")
-)
-store = Phronomy::StateStore::ActiveRecord.new(
-  model_class: PhronomyStateRecord,
-  encryptor: encryptor
-)
-```
-
-**Files to create:**
-- `lib/phronomy/state_store/encryptor/base.rb`
-- `lib/phronomy/state_store/encryptor/active_support.rb`
-- `lib/phronomy/state_store/encryptor.rb`
-
-**Files to modify:**
-- `lib/phronomy/state_store/active_record.rb` — accept `encryptor:`, apply in save/load
-- `lib/phronomy/state_store.rb` — require `encryptor`
-
-**Tests:**
-- Unit: `spec/phronomy/state_store/encryptor/base_spec.rb`
-- Unit: `spec/phronomy/state_store/encryptor/active_support_spec.rb`
-- Unit: extend `spec/phronomy/state_store_spec.rb` with encrypted save/load round-trip
-
----
-
-### Feature D — TTL and `purge` API on `ConversationManager`
-
-**Addresses:** 3.6 Privacy-Enhanced
-
-**Motivation:**
-Users have a right to be forgotten. `ConversationManager` currently has no way to
-delete stored messages for a given thread, nor does it enforce data retention limits.
-
-**Design:**
-- `ConversationManager#purge(thread_id:)` — deletes all stored messages for the
-  thread from both the storage backend and the retrieval index.
-- Optional `ttl:` constructor argument (Integer seconds | nil):
-  - When set, messages older than `ttl` seconds are filtered out on `load_messages`.
-  - Storage backends that support native TTL (e.g. Redis) should be informed via
-    a `Storage::Base#purge_older_than(thread_id:, older_than:)` hook.
-  - Default: `nil` (no expiry — current behaviour unchanged).
-- `Storage::ActiveRecord` gains a `purge_older_than` implementation using
-  `where("created_at < ?", Time.now - ttl).destroy_all`.
-
-**Usage example:**
-```ruby
-memory = Phronomy::Memory::ConversationManager.new(
-  storage: Phronomy::Memory::Storage::ActiveRecord.new(model_class: PhronomyMessageRecord),
-  ttl: 60 * 60 * 24 * 30  # 30 days
-)
-# Later:
-memory.purge(thread_id: "conv-123")
-```
-
-**Files to modify:**
-- `lib/phronomy/memory/conversation_manager.rb` — add `purge`, accept `ttl:`
-- `lib/phronomy/memory/storage/base.rb` — add `purge(thread_id:)` abstract method, `purge_older_than` hook
-- `lib/phronomy/memory/storage/active_record.rb` — implement both
-- `lib/phronomy/memory/storage/in_memory.rb` — implement both
-
-**Tests:**
-- Unit: extend `spec/phronomy/memory_spec.rb` with `purge` and TTL filtering tests
-- Unit: extend `spec/phronomy/active_record/message_spec.rb` with `purge_older_than`
-
----
-
-## Implementation Order
-
-| Step | Feature | Rationale |
-|---|---|---|
-| 1 | Feature A — BuiltinGuardrails | Self-contained, no dependencies, highest safety impact |
-| 2 | Feature B — Caller identity | Small change, high accountability value |
-| 3 | Feature C — Encryptor I/F | More complex, depends on no other feature |
-| 4 | Feature D — TTL / purge | Touches storage layer, do last to avoid churn |
-
-Each feature follows the same workflow:
-1. Implement source files
-2. Run StandardRB on new files
-3. Run unit tests: `bundle exec rspec <spec_file>`
-4. Run full unit suite: `bundle exec rspec --format progress`
-5. Run integration suite: `bundle exec rspec --tag integration --format progress`
-6. Present diff for commit approval
-
----
-
-## Out of Scope (This Branch)
-
-- Fairness metrics / demographic parity (`Eval::Metrics` extension) — domain-specific,
-  belongs to application layer
-- Kill switch / forced shutdown — infrastructure concern
-- Differential privacy — academic/research topic, not yet practical for gem scope
-- Authentication / authorisation — application / infrastructure concern