phronomy 0.22.0 → 0.23.0

data/benchmark/bench_context_assembler.rb

@@ -1,14 +1,10 @@
 # frozen_string_literal: true
 
-# Benchmark: Manifest-first Context assembly and Default Context Policy.
+# Benchmark: typed ContextPolicyInput and split Context assembly.
 #
 # 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"
@@ -17,66 +13,40 @@ require_relative "../lib/phronomy"
 module BenchContextAssembler
   module_function
 
-  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
-      }
-    )
+  def provenance
+    Phronomy::Agent::ContextPolicyInput::Provenance.new(origin: :journal)
   end
 
-  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
+  def policy_input(item_count)
+    knowledge = []
+    conversation = []
+    item_count.times do |index|
+      if (index % 10).zero?
+        knowledge << Phronomy::Agent::ContextPolicyInput::KnowledgeItem.new(
+          id: "knowledge-#{index}", kind: :knowledge, role: :user,
+          content: "knowledge #{index}", content_format: :text,
+          estimated_tokens: 8, required: false, provenance: provenance, metadata: {}
+        )
+      else
+        conversation << [Phronomy::Agent::ContextPolicyInput::ConversationItem.new(
+          id: "message-#{index}", kind: :external_message, role: :user,
+          content: "message #{index}", content_format: :text,
+          sequence: index, estimated_tokens: 8, required: false,
+          provenance: provenance, tool_call_id: nil, tool_call_ids: [],
+          delivery: :chat_message, metadata: {}
+        )]
+      end
+    end
 
-  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,
+    Phronomy::Agent::ContextPolicyInput.new(
+      agent_id: "bench-agent", execution_id: "bench-execution",
+      call_sequence: 2, call_mode: :complete,
+      instruction: [], knowledge: knowledge, tools: [], conversation: conversation,
       token_budget: Phronomy::LlmContextWindow::TokenBudget.new(
-        context_window: [candidate_count * 16, 4_096].max,
+        context_window: [item_count * 16, 4_096].max,
         max_output_tokens: 512
       ),
-      model_config: {},
-      previous_manifest: nil,
-      required_coverage: [],
-      parts: parts,
-      metadata: {"mandatory_token_estimate" => 32}
+      model_config: {}, previous_manifest: nil, metadata: {}
     )
   end
 
@@ -124,31 +94,32 @@ module BenchContextAssembler
   end
 end
 
-puts "Manifest-first Context benchmark"
+puts "Typed Context Policy benchmark"
 puts "Ruby #{RUBY_VERSION} on #{RUBY_PLATFORM}"
 puts "=" * 72
 
-policy = Phronomy::Agent::ContextPolicies::Default.new
-policy_requests = [10, 100, 1_000].to_h do |count|
-  [count, BenchContextAssembler.request(count)]
+policy = Phronomy::Agent::ContextPolicies::Default.instance
+policy_inputs = [10, 100, 1_000].to_h do |count|
+  [count, BenchContextAssembler.policy_input(count)]
 end
 
 Benchmark.bm(46) do |x|
-  policy_requests.each do |count, request|
+  policy_inputs.each do |count, policy_input|
     iterations = (count >= 1_000) ? 200 : 1_000
-    x.report("DefaultContextPolicy #{count} candidates x#{iterations}") do
-      iterations.times { policy.call(request) }
+    x.report("DefaultContextPolicy #{count} items x#{iterations}") do
+      iterations.times { policy.call(policy_input) }
     end
   end
 
   assembler, root, execution = BenchContextAssembler.assembler_fixture
-  x.report("ContextAssembler#build_initial x500") do
+  x.report("ContextAssembler prepare/finalize x500") do
     500.times do
-      assembler.build_initial(
+      prepared = assembler.prepare_initial(
         input: "benchmark input",
         agent_root: root,
         execution: execution
       )
+      assembler.finalize(prepared)
     end
   end
 end

data/benchmark/bench_regression.rb

@@ -97,7 +97,7 @@ end
 stub_agent_class = Class.new(Phronomy::Agent::Base) do
   agent_definition id: "bench-stub", version: 1
 
-  define_method(:invoke) do |_input, thread_id: nil, config: {}|
+  define_method(:invoke) do |_input, config: {}|
     {output: "stub", messages: []}
   end
 
@@ -112,7 +112,7 @@ stub_agent_class = Class.new(Phronomy::Agent::Base) do
   end
 end
 
-orchestrator_class = Class.new(Phronomy::MultiAgent::Orchestrator)
+orchestrator_class = Class.new(Phronomy::MultiAgent::Orchestrator) { agent_definition id: "orchestrator", version: 1 }
 orchestrator = orchestrator_class.new
 
 PARALLEL_ITERATIONS = 200

data/docs/architecture/agent-context.md

@@ -0,0 +1,174 @@
+> **CURRENT explanatory architecture**
+>
+> This document describes the reconciled current Phronomy system. Normative
+> architecture decisions remain in the [ADR index](../decisions/README.md);
+> source/runtime behavior remains implementation reality and does not silently
+> amend an ADR.
+
+# Agent Context, Identity, and Ownership
+
+## 1. System boundary
+
+A stateful Agent separates canonical durable facts, one live Runtime owner, and
+the logical input finalized for each Provider call.
+
+```text
+Application
+    |
+live Agent instance  -- agent_id --> one Runtime-local mutable owner
+    |
+    +-- AgentRoot / Journal view
+    |
+    +-- AgentExecution -- execution_id
+            |
+            +-- FSMSession incarnation -- fsm_session_id
+            |
+            +-- Provider Call -- llm_call_id
+            |
+            +-- ToolInvocation -- tool_invocation_id / tool_call_id
+```
+
+`agent_id` identifies the logical Agent. `execution_id` identifies one logical
+Agent execution. `fsm_session_id` identifies one Runtime execution incarnation.
+Provider and Tool semantic IDs identify their own operations. These identities
+are intentionally distinct.
+
+Phronomy does not restore a generic Agent `thread_id`, `session_id`,
+`correlation_id`, or `agent_invocation_id` identity. Application observability
+may use `InvocationContext#task_id` / `#parent_task_id`, but those values are not
+Agent, Workflow, Tool, or Runtime domain identities.
+
+Relevant decisions:
+[ADR-021](../decisions/021-generic-agent-invocation-identity-removal.md),
+[ADR-022](../decisions/022-agent-execution-parent-identity-and-runtime-routing-boundary.md),
+and [ADR-023](../decisions/023-fsm-session-incarnation-identity-and-routing.md).
+
+## 2. Canonical history and one-call input
+
+The Agent Journal is append-only canonical execution history. It is not the
+Provider message buffer.
+
+```text
+Journal / registered Knowledge / current-call material
+        |
+        v
+ContextPolicyInput
+  instruction / knowledge / tools / conversation
+        |
+        v
+ContextPolicy
+        |
+        v
+ContextPlan
+        |
+        v
+ContextAssembler
+        |
+        v
+LLMInputManifest
+        |
+        v
+RubyLLMMaterializer
+        |
+        v
+Provider
+```
+
+The finalized `LLMInputManifest` is the logical authority for one Provider Call.
+The Journal remains the canonical history authority. Context selection never
+rewrites old Journal facts.
+
+See [Context Management](context-management.md) and
+[ADR-012](../decisions/012-canonical-execution-log-and-context-policy.md).
+
+## 3. Live mutable ownership
+
+Within one Runtime/process, one mutable live Agent instance owns one `agent_id`.
+Loading or creating a second mutable live instance for the same `agent_id` is
+rejected.
+
+During active execution, EventLoop is the single writer of Phronomy-managed live
+Agent execution state. Blocking Persistence work and other synchronous work that
+must not run on EventLoop are submitted to OffloadPool. Worker results return as
+immutable operation-specific results and are applied only after EventLoop checks
+that the current execution/session/semantic-operation authority still matches.
+
+Persistence conflict detection protects durable state from stale writes. It is
+not a substitute for Runtime ownership.
+
+See
+[ADR-024](../decisions/024-event-loop-single-writer-agent-runtime.md) and
+[ADR-025](../decisions/025-process-local-agent-ownership-and-runtime-admission.md).
+
+## 4. Same-process and cross-process responsibility
+
+Same-process competing top-level Agent execution is rejected by Runtime
+admission. Cross-process competing-execution exclusion is **conditional**, not an
+unconditional Phronomy guarantee.
+
+A multi-process deployment must arrange stable routing/partitioning by logical
+identity or use an external coordination mechanism that establishes exclusive
+authority. Optimistic Persistence CAS/revision checks detect stale durable
+transitions; they do not themselves provide distributed exclusion.
+
+Phronomy does not currently add a distributed lease/fencing coordinator, live
+Agent migration protocol, or automatic takeover subsystem merely because
+Persistence is durable.
+
+See
+[ADR-018](../decisions/018-durability-guarantees-and-failure-model.md).
+
+## 5. Suspension, recovery, and process loss
+
+A live approval suspension retains the logical Agent execution slot. A later
+approval resumes the same logical `execution_id` with a new Runtime
+FSMSession incarnation as needed.
+
+After Runtime/process loss, process-local objects are gone. `Agent.load` uses
+confirmed durable state to classify unfinished work as:
+
+```text
+resumable
+reconcilable
+resolution_required
+```
+
+Recovery does not restore the old Ruby object graph or old Task callbacks. It
+reconstructs current logical state from durable evidence and continues only
+when authority and outcome certainty permit it.
+
+A finalized historical Manifest is reused for the Provider input it represents;
+Recovery does not rerun the historical Context Policy merely to reconstruct that
+Manifest.
+
+See [Persistence](persistence.md) for the durability/recovery boundary.
+
+## 6. Multi-Agent responsibility
+
+A semantic Handoff changes which live Agent is responsible for continuing the
+interaction. It does not merge Source and Target canonical state.
+
+Transferred Handoff Context is immutable request-scoped material. The Target
+Context Policy may select it for a Target LLM Call, but Handoff does not
+automatically append it to Target Journal or persistent Knowledge.
+
+Active Target responsibility persists across later Runner turns only within the
+same Runtime/main-Agent coordination lifetime. It is not durably rehydrated
+after Runtime/process reset.
+
+See [Multi-Agent Handoff](multi-agent-handoff.md).
+
+## 7. Removed models
+
+The following are not current Agent Context authorities:
+
+- mutable RubyLLM message history as canonical Agent state;
+- `Memory::ConversationManager`;
+- `LlmContextWindow::Assembler`;
+- `ContextVersionCache`;
+- a Static/Entity/RAG Knowledge source hierarchy;
+- a generic Agent conversation/thread/session identity;
+- cross-Agent Journal sharing as Handoff semantics.
+
+See [Removed Agent Context Architecture](removed/agent-context.md) for the
+negative guidance retained from the retired designs.

data/docs/architecture/before-llm-input.md

@@ -0,0 +1,78 @@
+> **CURRENT explanatory architecture**
+>
+> This document describes the reconciled current Phronomy system. Normative
+> architecture decisions remain in the [ADR index](../decisions/README.md);
+> source/runtime behavior remains implementation reality and does not silently
+> amend an ADR.
+
+# before_llm_input
+
+## 1. Purpose
+
+`before_llm_input` is the supported request-scoped customization boundary before
+a logical LLM input is finalized.
+
+It may adjust model configuration and add logical Context candidates without
+mutating Agent Journal state or a RubyLLM message buffer.
+
+## 2. Registration tiers
+
+Hooks may be configured globally, on an Agent class, or on one Agent instance.
+
+```text
+global -> class -> instance
+```
+
+Later model-configuration patches take precedence for the same key. Segment
+candidates are accumulated in hook order.
+
+## 3. Input and result
+
+Hooks receive immutable `Phronomy::Agent::LLMInputBuildContext` metadata. They do
+not receive a mutable Provider chat/message array.
+
+A hook returns `Phronomy::Agent::LLMInputPatch` or `nil`.
+
+```ruby
+Phronomy::Agent::LLMInputPatch.new(
+  model_config_patch: {temperature: 0.2},
+  segment_candidates: [
+    {
+      category: :knowledge,
+      role: :user,
+      content: "request-scoped retrieved context"
+    }
+  ]
+)
+```
+
+## 4. Context Policy boundary
+
+`segment_candidates` are candidate material, not preselected Manifest segments.
+
+They enter the same typed `ContextPolicyInput` path and may be selected, omitted,
+or otherwise handled by Application Policy subject to Framework invariants.
+
+Hook candidates are current-call material and are not automatically written to
+Journal or persistent Knowledge.
+
+## 5. Constraints
+
+A hook must not:
+
+- mutate Agent Journal state;
+- mutate RubyLLM Chat/messages;
+- assume an optional candidate will be selected;
+- forge Framework-reserved Context metadata;
+- bypass ContextPlan validation/canonicalization; or
+- bypass final token-budget validation.
+
+## 6. Trust/security
+
+Phronomy does not reinterpret `input_filter` as a universal Filter over hook
+candidates.
+
+Application ContextPolicy may inspect hook candidate provenance/metadata and
+apply domain-specific trust/security policy.
+
+See [Security Boundaries](security-boundaries.md).

data/docs/architecture/context-management.md

@@ -0,0 +1,232 @@
+> **CURRENT explanatory architecture**
+>
+> This document describes the reconciled current Phronomy system. Normative
+> architecture decisions remain in the [ADR index](../decisions/README.md);
+> source/runtime behavior remains implementation reality and does not silently
+> amend an ADR.
+
+# Context Management
+
+## 1. Authority model
+
+Phronomy separates canonical execution facts from the logical input of one LLM
+Call.
+
+```text
+Observed execution facts / registered Knowledge / current-call material
+        |
+        v
+JournalProjection + internal normalization
+        |
+        v
+ContextPolicyInput
+  instruction / knowledge / tools / conversation
+        |
+        v
+ContextPolicy#call
+        |
+        v
+ContextPlan
+  instruction / knowledge / tools / conversation
+        |
+        v
+ContextAssembler validation / canonicalization / final budget check
+        |
+        v
+LLMInputManifest
+        |
+        v
+RubyLLMMaterializer
+```
+
+- **Journal** is canonical append-only logical execution history.
+- **ContextPolicyInput** is an immutable typed snapshot of material eligible for
+  policy consideration.
+- **ContextPlan** expresses the Policy's semantic selection/order/generation.
+- **LLMInputManifest** is canonical logical input for one Provider Call.
+- **RubyLLMMaterializer** realizes that Manifest against runtime Provider/Tool
+  wiring; it is not another Context authority.
+
+The normative Journal/Manifest split is
+[ADR-012](../decisions/012-canonical-execution-log-and-context-policy.md).
+
+## 2. Public Context Policy SPI
+
+Application code supplies an ordinary reusable Ruby strategy object:
+
+```ruby
+class SearchContextPolicy < Phronomy::Agent::ContextPolicy
+  def initialize(search:)
+    @search = search
+  end
+
+  def call(input)
+    plan(
+      instruction: input.instruction,
+      knowledge: @search.call(input.knowledge),
+      tools: input.tools,
+      conversation: input.conversation
+    )
+  end
+end
+
+SEARCH_POLICY = SearchContextPolicy.new(search: SEARCH_SERVICE)
+
+class ResearchAgent < Phronomy::Agent::Base
+  context_policy SEARCH_POLICY
+end
+```
+
+`context_policy` binds a **Policy instance** on the Agent class. Policy
+construction/dependency injection are Application responsibilities. If the same
+instance is shared by multiple Agents/classes, its concurrency safety is also an
+Application responsibility.
+
+There are no Policy overrides on Agent create/load/invoke/stream and no durable
+Policy descriptor/registry. A currently loaded Application supplies the current
+Policy code.
+
+## 3. ContextPolicyInput
+
+`ContextPolicyInput` has four top-level semantic collections:
+
+```text
+instruction
+knowledge
+tools
+conversation
+```
+
+Instruction, Knowledge, Tool, and Conversation items are typed immutable values.
+
+Conversation is an ordered outer Array of immutable non-empty inner Arrays. Each
+inner Array is an indivisible selection group. Ordinary messages are singleton
+groups. An assistant Tool Call and the matching Tool-role message(s) are one
+atomic group and cannot be split by Policy selection.
+
+Policy input also carries execution/call/model/budget information needed for
+selection without exposing mutable Runtime state.
+
+## 4. ContextPlan and Framework validation
+
+The Plan uses the same four categories. Presence means selected; omission means
+omitted; order within a category is semantically meaningful.
+
+The Framework validates that:
+
+- selected input items came from the immutable request;
+- Policy-generated items use permitted generated-item rules;
+- required material is retained;
+- input conversation groups are not split, merged, or internally reordered;
+- generated conversation Tool protocol is structurally valid;
+- selected Tools resolve to the effective runtime Tool wiring;
+- Framework-owned metadata cannot be forged by Application content; and
+- the realized canonical input fits the final token budget.
+
+Provider/Manifest structural placement remains `ContextAssembler`
+responsibility.
+
+## 5. Policy-generated / compacted material
+
+An Application Policy may derive current-call material using the protected
+instruction/knowledge/conversation item helpers. This is also the supported
+shape for Application-defined semantic compaction:
+
+```text
+source optional Context
+    |
+Policy omits source item(s) for this call
+    +
+Policy creates derived current-call item
+    |
+ContextPlan
+```
+
+The original Journal facts are not deleted or rewritten. Generated content is
+current-call material unless the Application explicitly persists equivalent
+Knowledge through a separate supported mutation.
+
+Phronomy does not provide a parallel mutable "Memory Compression" subsystem, a
+fifth `derived` Plan collection, automatic summarization, or an extra built-in
+LLM call for the Default Policy.
+
+Required material cannot be silently compacted away. If required input cannot
+be accepted/represented within the applicable invariants and budget, Context
+preparation fails.
+
+## 6. Default Policy
+
+The built-in Default Policy is deterministic and model-free:
+
+- retain instruction material in stable order;
+- retain effective Tool definitions/order;
+- retain required/current conversation;
+- select an optional recent contiguous conversation window at group granularity;
+- select Knowledge in stable order, skipping an oversized optional item and
+  continuing;
+- use an approximate 60% conversation / 40% Knowledge split for variable
+  remainder and allow unused share to spill to the other category;
+- perform no vector retrieval, embedding/reranking, or automatic compaction.
+
+If required/fixed material does not fit, Context preparation fails rather than
+silently dropping it.
+
+## 7. Execution and Persistence boundary
+
+`ContextPolicy#call` is synchronous and runs on the Agent preparation Offload
+worker, not on EventLoop. No Phronomy Persistence transaction spans the Policy
+call.
+
+Preparation captures an immutable authoritative base, executes Application
+Policy outside the durable transaction, then revalidates Agent/Execution
+revision/watermark before the short commit/finalization path. A stale Policy
+result fails closed rather than overwriting newer durable state.
+
+Policy failure is not automatically retried and Phronomy does not silently fall
+back to another Policy.
+
+ContextPolicy is **not** one of the Framework's standard automatic tracing span
+types. Policy-internal retrieval/transformation tracing is Application-owned.
+See [Tracing](tracing.md).
+
+## 8. Recovery
+
+A finalized `LLMInputManifest` is the Recovery authority for the Provider input
+it represents. Recovery hydrates that Manifest rather than rerunning the
+historical Policy.
+
+Future calls use the Policy supplied by the currently loaded Application code.
+Agent/Workflow durability therefore does not depend on Policy object durability.
+
+## 9. Security/trust policy
+
+The Framework validates structure/integrity; it does not impose one universal
+semantic trust policy on arbitrary Context.
+
+Application-defined `ContextPolicy` is the semantic authority for source-aware
+selection, rejection/failure, redaction/sanitization, retrieval, reranking, or
+derived content needed for a particular LLM Call. Phronomy does not add a fourth
+universal `context_filter` call site.
+
+See [Security Boundaries](security-boundaries.md).
+
+## 10. Removed intermediate contracts
+
+The following are not current public Context Policy contracts:
+
+- `ContextRequest`;
+- `ContextPolicyDescriptor` / `ContextPolicyRegistry`;
+- `DerivedContentSpec`;
+- `ContextPlan#selected_unit_ids`;
+- `ContextPlan#derived_contents`;
+- `ContextPlan#ordering_hints`;
+- `ContextPlan#policy_descriptor`;
+- public `request.parts`;
+- `Selection::Unit` / `Selection::Validator`;
+- `DependencyAwareUnitBuilder`;
+- `RequiredContextResolver`;
+- `RecentFirstSelector`;
+- `TokenBudgetPacker`.
+
+Internal `Selection::Candidate` / `Selection::Constraint` normalization used
+while building the typed request does not create an Application DSL.