phronomy 0.15.1 → 0.17.0

data/benchmark/baseline.json

@@ -4,6 +4,5 @@
   "tool_params_schema_definition": 19534379.159046534,
   "dispatch_parallel_10": 886.0,
   "cancellation_token_cancelled": 4335060.97443425,
-  "cancellation_token_raise_if_cancelled_noop": 3566903.189098373,
-  "trim_messages_2000": 2896552.0
-}
+  "cancellation_token_raise_if_cancelled_noop": 3566903.189098373
+}

data/benchmark/bench_agent_invoke.rb

@@ -3,11 +3,11 @@
 # bench_agent_invoke.rb — Agent#invoke framework overhead benchmark.
 #
 # Measures the per-invoke cost of the Phronomy::Agent::Base framework path
-# (context assembly, guardrail checks, before_completion hooks, response
-# handling) with a fully stubbed LLM.  No network calls are made.
+# (context assembly, filter checks, before_llm_input hooks, response handling)
+# with a fully stubbed LLM. No network calls are made.
 #
 # Scenarios:
-#   1. Minimal agent (no tools, no knowledge) — baseline framework overhead.
+#   1. Minimal agent (no tools, no persistent Knowledge) — baseline framework overhead.
 #   2. Tool-aware agent with a registered stub Tool.
 #   3. Agent#stream setup latency (first-chunk time with stubbed stream).
 
@@ -40,6 +40,7 @@ class BenchStubChat
   def with_cache_instructions(_) = self
   def with_output_schema(_) = self
   def on_tool_call(&) = self
+  def before_tool_call(&) = self
   def last_message = @response
 
   def ask(_)
@@ -71,14 +72,16 @@ BENCH_RESP = BenchAgentMessage.assistant("benchmark complete")
 BENCH_RESP_CHAT = BenchStubChat.new(BENCH_RESP)
 
 bench_minimal_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-minimal", version: 1
   model "stub-model"
 
   define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end
 
 bench_tool_class = Class.new(Phronomy::Agent::Base) do
+  agent_definition id: "bench-tool", version: 1
   model "stub-model"
-  tools BenchNullTool
+  tools(BenchNullTool => nil)
 
   define_method(:build_chat) { |*| BenchStubChat.new(BENCH_RESP) }
 end

data/benchmark/bench_context_assembler.rb

@@ -1,54 +1,154 @@
 # frozen_string_literal: true
 
-# Benchmark: Context::Assembler#build
+# Benchmark: Manifest-first Context assembly and Default Context Policy.
 #
-# Tests context assembly performance for varying numbers of messages and
-# knowledge chunks. This path is exercised on every agent turn.
+# Usage:
+#   ruby benchmark/bench_context_assembler.rb
+#
+# Measures:
+#   1. ContextPolicies::Default selection cost for growing canonical candidate sets.
+#   2. ContextAssembler#build_initial end-to-end Manifest construction.
+#
+# No provider call is performed.
 
 require "benchmark"
 require_relative "../lib/phronomy"
 
-BenchAsmMessage = Struct.new(:content)
+module BenchContextAssembler
+  module_function
 
-def make_assembler(n_messages:, n_chunks:, with_budget: false)
-  budget = if with_budget
-    Phronomy::LlmContextWindow::TokenBudget.new(context_window: 4096, max_output_tokens: 512)
-  end
-  asm = Phronomy::LlmContextWindow::Assembler.new(budget: budget)
-  asm.add_instruction("You are a helpful assistant. Answer the user's question.")
-  n_chunks.times do |i|
-    asm.add_knowledge("Fact #{i}: The capital of country #{i} is City #{i}.", type: :entity, trusted: true)
+  def candidate(index)
+    category, role = if (index % 10).zero?
+      [:knowledge, :user]
+    elsif index.even?
+      [:assistant_message, :assistant]
+    else
+      [:external_message, :user]
+    end
+
+    Phronomy::Agent::ContextCandidate.new(
+      candidate_id: "candidate-#{index}",
+      source_kind: :journal,
+      category: category,
+      role: role,
+      content_ref: "content-#{index}",
+      record_id: "record-#{index}",
+      agent_id: "bench-agent",
+      execution_id: "execution-#{index / 4}",
+      llm_call_id: nil,
+      tool_call_id: nil,
+      sequence: index,
+      requirement: :optional,
+      priority: 0,
+      metadata: {
+        "estimated_tokens" => 8,
+        "source_sequence" => index
+      }
+    )
   end
-  msgs = Array.new(n_messages) { BenchAsmMessage.new("This is a conversation message.") }
-  asm.add_messages(msgs)
-  asm
-end
 
-BENCH_ASM_ITERATIONS = 1_000
+  def parts
+    {
+      unit_builder:
+        Phronomy::Agent::ContextParts::UnitBuilders::DependencyAwareUnitBuilder.new,
+      required_context_resolver:
+        Phronomy::Agent::ContextParts::Requirements::RequiredContextResolver.new,
+      recent_first_selector:
+        Phronomy::Agent::ContextParts::Selectors::RecentFirstSelector.new,
+      token_budget_packer:
+        Phronomy::Agent::ContextParts::Budget::TokenBudgetPacker.new
+    }.freeze
+  end
 
-puts "=== bench_context_assembler ==="
-Benchmark.bm(40) do |x|
-  x.report("build(10 msgs, 0 chunks)") do
-    BENCH_ASM_ITERATIONS.times { make_assembler(n_messages: 10, n_chunks: 0).build }
+  def request(candidate_count)
+    candidates = Array.new(candidate_count) { |i| candidate(i) }
+    Phronomy::Agent::ContextRequest.new(
+      agent_id: "bench-agent",
+      execution_id: "bench-execution",
+      call_sequence: 2,
+      call_mode: :complete,
+      candidates: candidates,
+      token_budget: Phronomy::LlmContextWindow::TokenBudget.new(
+        context_window: [candidate_count * 16, 4_096].max,
+        max_output_tokens: 512
+      ),
+      model_config: {},
+      previous_manifest: nil,
+      required_coverage: [],
+      parts: parts,
+      metadata: {"mandatory_token_estimate" => 32}
+    )
   end
 
-  x.report("build(100 msgs, 5 chunks)") do
-    BENCH_ASM_ITERATIONS.times { make_assembler(n_messages: 100, n_chunks: 5).build }
+  def assembler_fixture
+    persistence = Phronomy::Persistence::InMemory.new
+    agent_class = Class.new(Phronomy::Agent::Base) do
+      agent_definition id: "bench-manifest-context-assembler", version: 1
+      model "local-model"
+      context_window 16_384
+      max_output_tokens 1_024
+      instructions "Benchmark instruction"
+    end
+    agent = agent_class.new(
+      persistence: persistence,
+      knowledge: ["Persistent benchmark knowledge"]
+    )
+    root = agent.agent_root
+    input_ref = persistence.contents.put_text("benchmark input")
+    input_record = Phronomy::Agent::JournalRecord.new(
+      agent_id: agent.agent_id,
+      kind: :external_message,
+      channel: :external,
+      role: :user,
+      content_ref: input_ref,
+      context_generation: root.transcript_generation,
+      context_candidate: true
+    )
+    execution = Phronomy::Agent::AgentExecution.start(
+      agent_root: root,
+      input_record: input_record,
+      metadata: {
+        "current_input_ref" => input_ref,
+        "current_input_record_id" => input_record.record_id
+      }
+    ).with(
+      execution_revision: 0,
+      working_records: [input_record]
+    )
+
+    [
+      Phronomy::Agent::ContextAssembler.new(agent: agent, persistence: persistence),
+      root,
+      execution
+    ]
   end
+end
+
+puts "Manifest-first Context benchmark"
+puts "Ruby #{RUBY_VERSION} on #{RUBY_PLATFORM}"
+puts "=" * 72
 
-  x.report("build(1000 msgs, 10 chunks, no budget)") do
-    (BENCH_ASM_ITERATIONS / 10).times { make_assembler(n_messages: 1000, n_chunks: 10).build }
+policy = Phronomy::Agent::ContextPolicies::Default.new
+policy_requests = [10, 100, 1_000].to_h do |count|
+  [count, BenchContextAssembler.request(count)]
+end
+
+Benchmark.bm(46) do |x|
+  policy_requests.each do |count, request|
+    iterations = (count >= 1_000) ? 200 : 1_000
+    x.report("DefaultContextPolicy #{count} candidates x#{iterations}") do
+      iterations.times { policy.call(request) }
+    end
   end
 
-  x.report("build(1000 msgs, 10 chunks, budgeted)") do
-    (BENCH_ASM_ITERATIONS / 10).times do
-      # Assembler raises ContextLengthError when messages exceed the budget;
-      # callers (e.g. Agent::Base#build_context) are expected to pre-trim via
-      # trim_to_budget before calling build. The rescue here keeps the benchmark
-      # measuring build's fast path without triggering the error path.
-      make_assembler(n_messages: 1000, n_chunks: 10, with_budget: true).build
-    rescue Phronomy::ContextLengthError
-      # expected — budget exceeded
+  assembler, root, execution = BenchContextAssembler.assembler_fixture
+  x.report("ContextAssembler#build_initial x500") do
+    500.times do
+      assembler.build_initial(
+        input: "benchmark input",
+        agent_root: root,
+        execution: execution
+      )
     end
   end
 end

data/benchmark/bench_regression.rb

@@ -88,7 +88,8 @@ end
 # Target 4: Orchestrator#dispatch_parallel overhead (10 stub agents, no LLM)
 # ---------------------------------------------------------------------------
 stub_agent_class = Class.new(Phronomy::Agent::Base) do
-  define_method(:invoke) do |_input, messages: [], thread_id: nil, config: {}|
+  agent_definition id: "bench-stub", version: 1
+  define_method(:invoke) do |_input, thread_id: nil, config: {}|
     {output: "stub", messages: []}
   end
   define_method(:invoke_async) { |input, **_kw| Phronomy::Runtime.instance.spawn(name: "bench-stub") { invoke(input) } }
@@ -129,22 +130,6 @@ t6 = Benchmark.measure("CancellationToken#raise_if_cancelled! (no-op)") do
   RAISE_ITERATIONS.times { RAISE_TOKEN.raise_if_cancelled! }
 end
 
-# ---------------------------------------------------------------------------
-# Target 7: Agent::Base#trim_messages on a 2000-message history
-# ---------------------------------------------------------------------------
-BenchMsg = Struct.new(:content) unless defined?(BenchMsg)
-
-TRIM_MESSAGES = Array.new(2_000) { |i| BenchMsg.new("msg #{i}") }
-TRIM_ITERATIONS = 500
-
-bench_trim_agent = Class.new(Phronomy::Agent::Base).new
-
-t7 = Benchmark.measure("Agent::Base#trim_messages (2000-msg history)") do
-  TRIM_ITERATIONS.times do
-    bench_trim_agent.send(:trim_messages, TRIM_MESSAGES, keep: 1_800)
-  end
-end
-
 # ---------------------------------------------------------------------------
 # Print results and store in REGRESSION_RESULTS
 # ---------------------------------------------------------------------------
@@ -158,8 +143,7 @@ metrics = {
   "tool_params_schema_definition" => [t3, REGRESSION_ITERATIONS],
   "dispatch_parallel_10" => [t4, PARALLEL_ITERATIONS],
   "cancellation_token_cancelled" => [t5, 8 * CANCEL_ITERATIONS],
-  "cancellation_token_raise_if_cancelled_noop" => [t6, RAISE_ITERATIONS],
-  "trim_messages_2000" => [t7, TRIM_ITERATIONS]
+  "cancellation_token_raise_if_cancelled_noop" => [t6, RAISE_ITERATIONS]
 }
 
 REGRESSION_RESULTS = {} # rubocop:disable Style/MutableConstant

data/benchmark/bench_tool_schema.rb

@@ -1,16 +1,12 @@
 # frozen_string_literal: true
 
-# Benchmark: Tool::Base params_schema generation and static_knowledge_chunks cache
+# Benchmark: Tool::Base params_schema generation.
 #
-# Tool schema generation happens once per tool class (lazily memoised).
-# static_knowledge_chunks is cached at the class level; cache-hit overhead
-# should be negligible compared to cache-miss (which calls the knowledge source).
+# Tool schema generation happens once per tool class and is lazily memoized.
 
 require "benchmark"
 require_relative "../lib/phronomy"
 
-# --- Tool schema ---
-
 class BenchTool10Params < Phronomy::Agent::Context::Capability::Base
   description "A tool with 10 parameters for benchmarking purposes"
   param :param1, type: :string, desc: "First parameter"
@@ -29,7 +25,6 @@ class BenchTool10Params < Phronomy::Agent::Context::Capability::Base
   end
 end
 
-# Warm up memoisation
 BenchTool10Params.params_schema_definition
 
 BENCH_TOOL_ITERATIONS = 50_000
@@ -40,30 +35,3 @@ Benchmark.bm(35) do |x|
     BENCH_TOOL_ITERATIONS.times { BenchTool10Params.params_schema_definition }
   end
 end
-
-# --- static_knowledge_chunks cache ---
-
-class BenchKnowledgeSource < Phronomy::Agent::Context::Knowledge::Base
-  def fetch(query: nil)
-    [{content: "Cached knowledge fact.", type: :static}]
-  end
-
-  def static?
-    true
-  end
-end
-
-class BenchAgentWithKnowledge < Phronomy::Agent::Base
-  model "gpt-4o-mini"
-  static_knowledge BenchKnowledgeSource.new
-end
-
-# Warm up cache
-BenchAgentWithKnowledge.static_knowledge_chunks
-
-puts "\n=== bench_static_knowledge_cache ==="
-Benchmark.bm(35) do |x|
-  x.report("static_knowledge_chunks (hit)") do
-    BENCH_TOOL_ITERATIONS.times { BenchAgentWithKnowledge.static_knowledge_chunks }
-  end
-end

data/docs/decisions/005-static-knowledge-class-level-cache.md

@@ -2,7 +2,12 @@
 
 ## Status
 
-Accepted
+Superseded by ADR-013.
+
+This ADR records the historical decision for the former KnowledgeSource-based
+architecture. `static_knowledge`, `KnowledgeSource`, `StaticKnowledge`,
+`EntityKnowledge` and the class-level Knowledge cache are no longer part of the
+active design.
 
 ## Context
 
@@ -43,3 +48,9 @@ re-fetched on each invocation because their content depends on runtime state.
   non-static knowledge source.
 - In tests, the cache must be cleared between examples. `Phronomy.reset_runtime!`
   handles this.
+
+## Supersession
+
+ADR-013 replaces the source-object/cache model with Journal-backed persistent
+Knowledge selected through Context Policy. The historical rationale above is
+retained only to explain the superseded architecture.

data/docs/decisions/010-cooperative-first-concurrency.md

@@ -5,6 +5,13 @@
 Accepted — updated 2026-05-25 to document current scheduler landscape and
 production-cooperative roadmap (Issues #331, #332, #334).
 
+> **Historical implementation note (2026-08-09):** The implementation-detail
+> inventory below is intentionally preserved as decision history. Compatibility
+> APIs subsequently removed from the active contract — including the
+> `runtime_backend :cooperative` alias and direct Runtime singleton replacement —
+> must not be read as current API guidance. The cooperative-first layering
+> principle remains the decision; use README/current source for current symbols.
+
 ## Context
 
 Phronomy provides its own concurrency primitives:

data/docs/decisions/011-build-context-as-single-llm-input-authority.md

@@ -2,7 +2,46 @@
 
 ## Status
 
-Proposed — 2026-05-31
+Superseded by ADR-012 — 2026-08-08
+
+Originally proposed — 2026-05-31.
+
+## Supersession Note
+
+ADR-012, **Canonical Complete Execution Log and Context Policy**, supersedes this ADR as an active architecture contract. This document is retained as historical design analysis; references below to `build_context`, `context_overhead`, and `LlmContextWindow::Assembler` are non-normative.
+
+In particular, the following parts of this ADR are no longer normative for the stateful Agent architecture:
+
+* **D1 — `build_context` is the single authority for all LLM input**
+* **D2 — Assembler handles all four regions including Capability**
+* **D3 — `build_context` includes all tools**
+* **D5 — Previous context stored as an instance variable**
+
+The replacement authority model is:
+
+```text
+Canonical Journal
+      ↓
+Context Policy
+      ↓
+LLM Call Manifest
+      ↓
+Runtime Projection
+      ↓
+RubyLLM / Provider
+```
+
+Under ADR-012:
+
+* the **Journal** is authoritative for logical execution facts observed by Phronomy;
+* the **Manifest** is authoritative for the logical input fixed for one specific LLM Call;
+* Context Policy determines which canonical history is selected for that Manifest;
+* selection, pruning, and compaction do not delete or rewrite the canonical Journal;
+* Tool protocol dependencies are preserved independently from semantic Context-selection policy.
+
+The problem statements and historical analysis in this ADR remain useful as design history. Decisions or implementation notes that do not conflict with ADR-012 may still describe valid constraints, but ADR-012 is authoritative whenever the two documents differ.
+
+See: `012-canonical-execution-log-and-context-policy.md`
 
 ## Context
 

data/docs/decisions/012-canonical-execution-log-and-context-policy.md

@@ -0,0 +1,69 @@
+# 012 — Canonical Complete Execution Log and Context Policy
+
+## Status
+
+Accepted for the stateful Agent refactor. This decision supersedes the parts of ADR-011 that made the legacy `build_context`/Assembler path the long-term LLM-input authority.
+
+## Decision
+
+Phronomy records the logical execution facts it observes as an append-only Canonical Complete Execution Log. Context selection, pruning and compaction do not rewrite or delete those raw facts. They decide only which representation is materialized into one LLM Call Manifest.
+
+Journal and Manifest are separate authorities:
+
+- **Journal** is the authoritative record of logical execution facts that Phronomy observed.
+- **Manifest** is the authoritative record of the logical input fixed for one particular LLM Call.
+- Runtime Projection is derived from the Manifest and must not add semantic content that the Manifest did not select.
+
+The persistent identity axes have narrow responsibilities:
+
+- `agent_id` identifies the owning Agent.
+- `execution_id` identifies one AgentExecution. It is provenance, not a Context-selection atom.
+- `llm_call_id` identifies one runtime Provider LLM Call. It is allocated before transport starts and correlates that call's outcome. It is provenance, not a semantic-compaction boundary.
+- `tool_call_id` links an assistant message's Tool Call with the corresponding Tool execution/message.
+- Journal `sequence` is canonical chronology.
+
+No `message_group_id`, import-only source provenance ID, or synthetic imported `execution_id` / `llm_call_id` is introduced.
+
+### Message preservation
+
+A logical message that Phronomy receives is not flattened merely to make later Context assembly convenient.
+
+- A Provider assistant response is captured as one complete assistant message containing its observable `content` and all Tool Calls.
+- An imported assistant message is journaled as one assistant message with the structure supplied by the Import contract.
+- A Tool value returned by Phronomy Tool execution is an execution fact (`tool_result`).
+- The Tool-role message actually appended to the LLM conversation is a separate logical fact (`tool_message`).
+- Imported Tool-role messages are journaled directly as `tool_message` records; Phronomy does not invent a separate raw Tool execution result for an execution it did not observe.
+
+The Journal therefore does not need to infer or reconstruct a source message boundary that Phronomy already observed. Context Policy can inspect Tool Call IDs contained in an assistant message and form protocol-safe selection units with the corresponding Tool messages.
+
+### Import boundary
+
+The application supplying imported history is responsible for satisfying Phronomy's Import contract. Phronomy interprets valid input according to that contract and rejects only data that is invalid under the contract, such as unsupported roles, missing Tool Call IDs, orphan/duplicate Tool results, unresolved Tool calls, or malformed message structure.
+
+External resource acquisition is not a `ContextImporter` responsibility. Files, URLs and similar resources are obtained and interpreted by the Application or Tool that owns that capability; Phronomy journals the logical content/results it actually receives. `ContextImporter` therefore does not introduce RubyLLM-specific attachment handling or an attachment-specific reject path.
+
+Phronomy must not reject an otherwise valid input merely because an internal flattened representation would lose information. In particular, two separately supplied assistant messages remain two separate Journal messages.
+
+### Manifest boundary
+
+The Manifest fixes what one LLM Call will actually receive after Context Policy selection. A historical raw Tool return value and the Tool message produced from it are not interchangeable: the raw result belongs to the execution log, while the message selected for an LLM Call belongs to the Manifest input path.
+
+One Provider response is captured as a Phronomy-owned `ProviderCallOutcome` before Agent-owned Tool execution starts. The canonical assistant-message record is produced from that outcome, not from Application callback delivery.
+
+Context selection is expressed separately through `ContextCandidate`, dependency-aware `ContextSelectionUnit`, `ContextRequest`, `ContextPolicy`, validated `ContextPlan`, and final token-budget validation. An assistant message containing Tool Calls and the corresponding Tool messages form an atomic protocol unit. Ordinary messages in the same `execution_id` remain independently selectable.
+
+## RubyLLM boundary
+
+Agent-owned Tool execution requires RubyLLM's additive callback contract introduced in RubyLLM 1.15. Phronomy therefore requires `ruby_llm >= 1.15, < 2`.
+
+RubyLLM 1.15 adds the complete assistant message to `Chat#messages` before `before_tool_call` callbacks run. Phronomy captures the immutable Provider outcome at that boundary and raises `ToolCallIntercepted` only as an internal control transfer so approval, suspension, parallel dispatch and durable state remain Phronomy-owned.
+
+## Consequences
+
+- Canonical execution history is independent of the current Context budget or policy.
+- Import and runtime histories converge on the same canonical assistant/tool-message model without synthetic grouping identity.
+- Old optional working history may be excluded from a follow-up Manifest without being deleted.
+- Raw Tool results remain available as execution facts even when the corresponding Tool message is omitted from a later Manifest.
+- Tool protocol dependencies are validated independently from semantic selection policy.
+- Context Policy can later introduce deterministic derived/compacted records without replacing their raw sources.
+- Public custom Context Policy APIs, transaction-boundary restructuring, deterministic compaction, Manifest v2/tool subsets, and legacy Assembler removal remain later phases.

data/docs/decisions/013-journal-backed-knowledge-as-context-candidates.md

@@ -0,0 +1,122 @@
+# ADR-013: Journal-backed Knowledge as Context Candidates
+
+## Status
+
+Accepted.
+
+## Context
+
+The Manifest-first Agent refactor established the Journal as the canonical
+append-only record of Agent state and `LLMInputManifest` as the authority for
+one provider call. The older Knowledge design remained outside that model:
+`StaticKnowledge` and other `KnowledgeSource` objects were fetched separately,
+then concatenated into the mandatory system prompt. That created several
+problems:
+
+- static/entity/RAG distinctions described acquisition strategy rather than
+  Context semantics;
+- class-level and instance-level Knowledge followed different storage paths;
+- persistent Knowledge did not share Agent persistence/reload semantics;
+- Knowledge bypassed Context Policy and was always mandatory once configured;
+- `static?`, `source`, fetch/caching APIs and EntityKnowledge behavior existed
+  primarily to support the obsolete source abstraction.
+
+Applications still need two different lifetimes:
+
+1. information that becomes durable Agent Knowledge at creation time or later;
+2. request-scoped information used for only one LLM call.
+
+## Decision
+
+Phronomy has one Knowledge Context category.
+
+### Persistent Knowledge
+
+Persistent Knowledge is stored as ordinary append-only Journal records with
+`kind: :knowledge`, `channel: :context`, `role: :user` and
+`context_candidate: true`. Content lives in ContentStore and the Journal holds
+its content reference and application metadata.
+
+Agent instances accept Knowledge at creation and after creation:
+
+```ruby
+agent = MyAgent.new(knowledge: ["Policy: ..."])
+agent.add_knowledge("Customer locale: ja-JP")
+```
+
+`Agent.load` requires no separate Knowledge source reconstruction because the
+records are already persisted with the Agent.
+
+### Selection
+
+Knowledge is not part of the public conversation transcript.
+`JournalProjection` exposes active Knowledge together with active transcript
+records for Context selection. `ContextCandidateResolver` and Context Policy
+therefore handle persistent Knowledge through the same selection pipeline as
+other optional Context.
+
+Knowledge is optional by default. The fact that content is Knowledge does not
+make it mandatory.
+
+Selected Knowledge is materialized before ordinary conversation-history
+segments so that persistent background Context is not interleaved into the
+middle of dialogue chronology.
+
+### Reset semantics
+
+`clear_knowledge!` appends a `knowledge_cleared` marker. Earlier Knowledge
+records remain in the Journal but are excluded from later Context projections.
+No Knowledge-generation counter is required.
+
+`clear_transcript!` affects conversation history only. `reset_context!` resets
+both transcript eligibility and Knowledge eligibility while retaining raw
+Journal records.
+
+### Per-call Context
+
+`before_llm_input` continues to accept `LLMInputPatch#segment_candidates`.
+Those candidates are not persisted. They enter the same Context Policy request
+as Journal-backed candidates and may be omitted when optional and over budget.
+
+### Acquisition responsibility
+
+Phronomy core does not model `StaticKnowledge`, `EntityKnowledge`,
+`RAGKnowledge` or `KnowledgeSource` subclasses. File loading, retrieval, entity
+extraction and other acquisition strategies belong to applications or Tools.
+Once an application chooses to retain the resulting information, it registers
+plain logical Knowledge with the Agent.
+
+## Consequences
+
+### Positive
+
+- one persistent representation and one Context-selection path;
+- creation-time and post-creation Knowledge behave identically;
+- durable Knowledge naturally survives Agent reload;
+- token-budget selection can omit optional Knowledge without rewriting state;
+- RAG/entity extraction can evolve independently of Agent Context persistence;
+- no class-level static cache or `static?` distinction is needed.
+
+### Tradeoffs
+
+- applications that previously declared class-level static Knowledge must pass
+  common Knowledge when constructing each Agent instance;
+- source-specific refresh behavior is no longer a framework abstraction;
+- provenance that matters to an application must be stored explicitly in
+  metadata rather than through a dedicated `source:` API.
+
+## Removed contracts
+
+This decision removes the active contracts for:
+
+- `Phronomy::KnowledgeSource`;
+- `Agent::Context::Knowledge::Base`;
+- `StaticKnowledge`;
+- `EntityKnowledge`;
+- `static_knowledge`, `static_knowledge_sources`, `static_knowledge_chunks`,
+  `static_knowledge_refresh!`;
+- `add_knowledge_source`, `instance_knowledge_chunks`;
+- `clear_memory!` / `memory_generation` as obsolete Agent Context concepts.
+
+ADR-005 is superseded by this decision. ADR-012 remains the authority for the
+Journal/Manifest separation and Context Policy model.

data/lib/phronomy/agent/activation_registry.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ActivationRegistry
+      def initialize
+        @mutex = Mutex.new
+        @records = {}
+      end
+
+      def register(activation)
+        @mutex.synchronize do
+          raise ArgumentError, "activation already registered: #{activation.execution_id}" if @records.key?(activation.execution_id)
+          @records[activation.execution_id] = activation
+        end
+        activation
+      end
+
+      def fetch(execution_id)
+        @mutex.synchronize { @records[execution_id.to_s] }
+      end
+
+      def delete(execution_id)
+        @mutex.synchronize { @records.delete(execution_id.to_s) }
+      end
+    end
+  end
+end