phronomy 0.22.0 → 0.24.0

data/docs/decisions/019-filter-contract-and-security-boundaries.md

@@ -0,0 +1,229 @@
+# ADR-019: Filter Contract and Security Boundaries
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-08-23
+
+## Context
+
+Phronomy's live implementation and public API have moved from the former
+`Guardrail::*` hierarchy to a unified `Phronomy::Filter::Base` model.
+
+The old architecture described separate `InputGuardrail` and
+`OutputGuardrail` base classes, `GuardrailError`, `*_guardrail` registration
+APIs, and a built-in PII detector. Those APIs no longer exist. Current source
+instead exposes explicit Filter call sites for input, output, and Tool
+results, with one Filter abstraction that can transform a value or reject it.
+
+ADR-006 preserved useful policy intent — especially avoiding a false sense of
+complete generic security and keeping domain-specific policy
+application-owned — but its normative API vocabulary still described the
+removed Guardrail hierarchy. Leaving that ADR normative makes architecture
+authority disagree with the current Filter contract.
+
+This ADR supersedes ADR-006 for the current Filter/security-policy
+architecture while preserving ADR-006 as decision history.
+
+## Decision
+
+### 1. `Filter::Base` is the current policy-interception abstraction
+
+The current public abstraction is:
+
+```ruby
+Phronomy::Filter::Base
+```
+
+A Filter receives a value at an explicitly defined call site and may:
+
+1. return the original value;
+2. return a transformed value; or
+3. reject the value by raising `Phronomy::FilterBlockError`, normally through
+   `Filter::Base#block!`.
+
+A Filter is not divided into InputFilter/OutputFilter subclasses. The same
+Filter instance may be registered at more than one call site when that is
+appropriate for the application.
+
+### 2. Filter call sites remain explicit
+
+Current Agent Filter registration supports distinct call sites:
+
+```text
+input
+output
+Tool result
+```
+
+Multiple Filters at one call site run in registration order. A blocking
+Filter short-circuits later processing through `FilterBlockError`.
+
+The call-site distinction is semantically important. A Filter registered for
+one site does not silently become a universal content-inspection hook.
+
+### 3. Input Filter means raw invocation-input filtering today
+
+The current `input_filter` / `add_input_filter` path applies to raw invocation
+input before later Context assembly.
+
+It does **not** automatically inspect every value that may later contribute to
+an LLM input, including all Knowledge, retrieval results, Tool-derived
+Context, or `before_llm_input` `segment_candidates`.
+
+This ADR does not decide whether Phronomy should add a dedicated
+Context-candidate inspection point. That broader trust-boundary question
+remains the separate Filter/Security Boundary review.
+
+### 4. `PromptInjectionFilter` is a bounded heuristic baseline
+
+Phronomy may provide the lightweight built-in:
+
+```ruby
+Phronomy::Filter::PromptInjectionFilter
+```
+
+as a convenience baseline for common prompt-injection patterns.
+
+This Filter is a heuristic pattern detector. Its presence does not mean:
+
+- all prompt injection is detected;
+- every untrusted Context source is automatically inspected;
+- Filter registration establishes an LLM security sandbox; or
+- Phronomy provides a complete content-security guarantee.
+
+Applications remain responsible for selecting appropriate Filter call sites
+and for additional domain-specific controls.
+
+### 5. Generic built-in PII policy is not a Phronomy core guarantee
+
+The removed `PIIPatternDetector` architecture is not carried forward.
+
+PII definitions, locale-specific identifiers, compliance requirements and
+transformation/rejection policy are application/domain responsibilities
+unless a future explicit architecture decision introduces a new contract.
+
+Applications can implement these policies as `Filter::Base` subclasses or
+application-owned components.
+
+### 6. Filter/approval/offload are not process-security isolation
+
+Filter, Tool approval, EventLoop/OffloadPool execution boundaries and
+application authorization are distinct mechanisms.
+
+None of them, by itself, promises:
+
+- OS process isolation;
+- container isolation;
+- filesystem/network sandboxing;
+- privilege separation; or
+- containment of arbitrary malicious Tool/application code.
+
+If an application needs those properties, the isolation mechanism is
+application/deployment-owned unless Phronomy later defines a specific
+sandbox SPI.
+
+### 7. Removed Guardrail contracts stay removed
+
+The following legacy architecture is not a current compatibility contract and
+must not be reintroduced merely for naming compatibility:
+
+```text
+Phronomy::Guardrail::Base
+Phronomy::Guardrail::InputGuardrail
+Phronomy::Guardrail::OutputGuardrail
+Phronomy::GuardrailError
+add_input_guardrail
+add_output_guardrail
+input_guardrail
+output_guardrail
+```
+
+Current code uses `Filter::Base`, `FilterBlockError`, and explicit
+`*_filter` registration APIs.
+
+### 8. Historical Guardrail documentation
+
+`docs/archive/design/archived/09_guardrails.md` records the removed Guardrail design. It is
+non-normative and is not rewritten into current Filter architecture.
+
+The physical move to the repository archive was completed by ACS-02
+(canonical architecture documentation lifecycle migration).
+
+### 9. Security-boundary questions deferred at ADR acceptance
+
+At the time this ADR was accepted, this decision deliberately did not
+settle the broader Filter/Security Boundary review, including:
+
+- whether and where all untrusted Context candidates require inspection;
+- whether a dedicated pre-Manifest Context inspection stage is needed;
+- stronger PromptInjectionFilter guarantees;
+- Tool sandbox architecture;
+- or a new public security-policy SPI.
+
+Those questions must not be smuggled into the current Filter contract by
+changing call-site semantics implicitly.
+
+## Follow-up security-boundary review
+
+The subsequent D02-F02 reconciliation review closed the Context-inspection
+question without broadening the Filter SPI:
+
+- no fourth `context_filter` / `add_context_filter` call site is added;
+- Application `ContextPolicy` is the semantic trust/selection authority for
+  one LLM Call's typed Context;
+- Framework validation remains structural/integrity validation rather than
+  arbitrary semantic filtering;
+- Tool approval remains authorization rather than sanitization or sandboxing;
+- OS/process/container/filesystem/network isolation remains an
+  Application/deployment concern.
+
+The current explanatory boundary is
+[`docs/architecture/security-boundaries.md`](../architecture/security-boundaries.md).
+
+## Supersession
+
+This ADR supersedes
+[`006-no-built-in-guardrails`](006-no-built-in-guardrails.md) as the normative
+Filter/security-policy architecture.
+
+ADR-006 remains preserved as history explaining the earlier minimal-built-in
+policy and its later prompt-injection exception.
+
+## Consequences
+
+### Positive
+
+- normative architecture now matches the live Filter model;
+- old Guardrail class names cannot be mistaken for current public contracts;
+- useful "avoid false confidence" policy intent from ADR-006 is retained;
+- Filter behavior and security-isolation guarantees remain distinct;
+- current raw-input filtering is not falsely described as universal Context
+  inspection; and
+- broader security-boundary design can proceed without being pre-decided by
+  terminology cleanup.
+
+### Trade-offs
+
+- applications needing PII/domain policy continue to supply that policy
+  themselves; and
+- the built-in PromptInjectionFilter remains intentionally modest rather than
+  a complete security solution.
+
+## Non-goals
+
+This ADR does not:
+
+- change Filter runtime behavior or ordering;
+- change the current raw-input `input_filter` placement;
+- automatically apply input Filters to Knowledge/RAG/hook Context;
+- add a Context-candidate inspection API;
+- add OS/process/container Tool sandboxing;
+- change Tool approval semantics;
+- change Persistence or durable representation;
+- make Filter stability stronger than the public feature catalog currently
+  states; or
+- perform the final `spec/design/*` path migration.

data/docs/decisions/020-canonical-workflow-instance-identity.md

@@ -0,0 +1,177 @@
+# ADR-020: Canonical Workflow Instance Identity
+
+## Status
+
+Accepted.
+
+## Date
+
+2026-08-23
+
+## Context
+
+Phronomy currently uses `thread_id` for the logical/durable identity of a
+Workflow. The value does not identify a Ruby or operating-system Thread. It
+identifies one logical Workflow instance across invoke, halt, resume, live
+signal routing, and `Persistence#workflow_states`.
+
+At the same time, `FSMSession#id` identifies one concrete Runtime FSM
+incarnation. One logical Workflow may use more than one FSMSession over its
+lifetime. Reusing the generic name `thread_id` for the Workflow domain identity
+therefore obscures the boundary between durable identity and Runtime routing.
+
+ADR-014 records the earlier `thread_id` terminology. The architecture
+reconciliation program resolved this terminology under CG-01 / ACS-13. This ADR
+makes that narrow identity decision repository authority without pulling the
+remaining Workflow admission-owner, terminal durability, fencing, or recovery
+changes into the same implementation slice.
+
+## Decision
+
+### 1. `workflow_instance_id` is the canonical Workflow identity
+
+The canonical logical Workflow identity is:
+
+```text
+workflow_instance_id
+  = one logical Workflow instance
+  = the logical Persistence#workflow_states key when the Workflow is durable
+```
+
+`thread_id` is not retained as a Workflow architecture term.
+
+`workflow_instance_id` is framework-owned WorkflowContext metadata, not an
+application state field. Applications must not declare
+`WorkflowContext.field(:workflow_instance_id)`; Phronomy rejects that declaration
+to prevent application state from shadowing or persisting the canonical Workflow
+identity. Applications already using that field name must rename their
+application field when adopting this identity contract.
+
+### 2. The migration is a clean break
+
+Public and extension surfaces change directly:
+
+```text
+WorkflowContext#thread_id
+  -> WorkflowContext#workflow_instance_id
+
+Workflow#signal(thread_id:)
+  -> Workflow#signal(workflow_instance_id:)
+
+Workflow invocation config[:thread_id]
+  -> config[:workflow_instance_id]
+
+WorkflowStateRepository load/save/delete parameter meaning
+  thread_id
+  -> workflow_instance_id
+```
+
+No deprecated Workflow `thread_id` alias is provided.
+
+The removed Workflow config key is rejected explicitly rather than ignored.
+Silently ignoring it could allocate a fresh identity and branch durable Workflow
+history, which is more dangerous than a visible migration error.
+
+### 3. Durable identifier values do not change
+
+This decision renames the semantic parameter, not the identifier value.
+
+```text
+old durable key value: "order-123"
+new durable key value: "order-123"
+```
+
+Existing durable values remain the identity of the same logical Workflow
+instance. A backend does not need to generate replacement identifiers.
+
+The Persistence Backend SPI uses `workflow_instance_id` as the logical parameter
+name and meaning. A backend may keep an existing physical database column or key
+name internally; this ADR does not require a physical schema rename solely for
+terminology.
+
+### 4. Workflow identity is not inherited from generic InvocationContext identity
+
+Workflow invocation does not implicitly copy `InvocationContext#thread_id` into
+its domain identity.
+
+If an application needs durable Workflow identity, it supplies
+`workflow_instance_id` explicitly through the Workflow API/configuration.
+
+This decision does not remove Agent/correlation `thread_id` surfaces from
+`InvocationContext` or Agent APIs. Their generic-identity reconciliation is a
+separate Compatibility Gate.
+
+### 5. FSMSession identity remains separate
+
+`FSMSession#id` / `fsm_session_id` identifies one concrete Runtime FSM
+incarnation and is not the Workflow domain identity.
+
+CG-01 does not rename the shared Runtime-internal `graph_thread_id` bridge used
+by `FSMSession`. WorkflowRunner may continue to pass the canonical
+`workflow_instance_id` value through that existing generic bridge so that a
+replacement WorkflowContext receives the same durable identity before halt or
+finish. WorkflowContext maps that Runtime-internal metadata onto
+`workflow_instance_id`; this does not create a public `thread_id` accessor,
+Workflow config key, signal keyword, or deprecated Workflow API alias. Renaming
+the shared FSMSession graph-metadata protocol belongs to the separate Runtime
+identity reconciliation.
+
+```text
+Workflow W1
+  workflow_instance_id = W1
+
+  FSMSession S1
+    id = S1
+      -> halt
+
+  FSMSession S2
+    id = S2
+      -> resume / finish
+```
+
+No `workflow_execution_id` is introduced by this decision.
+
+### 6. This ADR supersedes only ADR-014 Workflow identity terminology
+
+ADR-014 remains historical and current authority for the portions not superseded
+here. Wherever ADR-014 calls the logical/durable Workflow identity `thread_id`,
+this ADR replaces that terminology with `workflow_instance_id`.
+
+The current admission-owner representation and terminal-save ordering are not
+made normative by this ADR merely because the current implementation still
+contains them.
+
+## Consequences
+
+### Positive
+
+- The Workflow domain identity says what it identifies.
+- Durable Workflow identity and Runtime FSMSession identity are no longer named
+  as if they were the same kind of session/thread concept.
+- Persistence backend implementations receive an unambiguous logical SPI
+  parameter name.
+- Existing durable identifier values can continue unchanged.
+- A removed config key cannot silently create a new durable identity.
+
+### Trade-offs
+
+- This is a pre-1.0 breaking API/SPI change.
+- Applications using `config[:thread_id]`, `WorkflowContext#thread_id`, or
+  `Workflow#signal(thread_id:)` must migrate.
+- Custom Persistence backends should update method parameter names and
+  documentation even when their physical database schema remains unchanged.
+
+## Explicit non-goals
+
+CG-01 does not decide or implement:
+
+- replacement of Workflow admission ownership by an opaque owner token/handle;
+- durable terminal/halt save as an FSM barrier before logical terminalization;
+- EventLoop/FSMSession ownership redesign beyond identity nomenclature;
+- cross-process ownership, leases, or fencing;
+- process-loss recovery or rehydration;
+- Agent/InvocationContext generic identity removal;
+- a new `workflow_execution_id`.
+
+Those concerns remain separate architecture-reconciliation work and must not be
+inferred from this identity-only decision.

data/docs/decisions/021-generic-agent-invocation-identity-removal.md

@@ -0,0 +1,119 @@
+# ADR 021: Generic Agent Invocation Identity Removal
+
+**Status**: Accepted  
+**Date**: 2026-08-23  
+**Partially supersedes**: [ADR-014](014-unified-persistence-durable-state.md) for `InvocationContext` generic session/correlation semantics and Agent-side generic invocation identity
+
+---
+
+## Context
+
+Phronomy historically exposed `thread_id` and `session_id` as generic
+invocation metadata. Agent `thread_id` was copied through execution metadata,
+Journal `correlation_id`, Manifest model configuration, and Multi-Agent child
+dispatch, but it did not identify Agent ownership, durable Agent state, resume,
+or Runtime event routing.
+
+`InvocationContext#session_id` likewise did not correspond to a Phronomy-owned
+session domain object or lifecycle. Renaming either value to another generic
+identity such as `correlation_id`, `conversation_id`, or
+`application_session_id` would preserve the ambiguity instead of resolving it.
+
+Phronomy already has purpose-specific semantic identifiers such as
+`execution_id`, `llm_call_id`, `tool_invocation_id`, `tool_call_id`,
+`approval_request_id`, `workflow_instance_id`, and Runtime-local
+`FSMSession#id`. Tracing task identifiers are a separate observability concern.
+
+## Decision
+
+Generic Agent invocation identity is removed as a clean break.
+
+The public contract does not include:
+
+```text
+InvocationContext#thread_id
+InvocationContext#session_id
+
+Agent#invoke(thread_id:)
+Agent#invoke_async(thread_id:)
+Agent#stream(thread_id:)
+Agent#stream_async(thread_id:)
+```
+
+The same generic value is not propagated through Multi-Agent child dispatch,
+AgentExecution metadata, approval context, or finalized LLM model
+configuration.
+
+No replacement generic identity field is introduced.
+
+`InvocationContext#task_id` and `#parent_task_id` remain tracing /
+observability identifiers. They are not promoted to Agent, Workflow, Tool, or
+Runtime domain identity.
+
+Agent configuration rejects legacy `thread_id` and `session_id` keys at
+execution/resume boundaries rather than retaining an untyped compatibility
+backdoor.
+
+## Durable Journal migration
+
+The architecture decision also removes generic `JournalRecord#correlation_id`
+from the new canonical representation. Existing durable Journal data is not
+rewritten merely to remove that field.
+
+Implementation is staged:
+
+```text
+CG-02a
+  public / non-durable generic identity removal
+  status: reconciled by the CG-02a change
+
+CG-02b
+  remove correlation_id from the new canonical Journal representation
+  accept/ignore the legacy key during backward read
+  no eager durable rewrite
+  status: reconciled by the CG-02b change
+```
+
+`JournalRecord.from_h` intentionally reconstructs only current canonical
+attributes. A legacy durable Hash may therefore contain `correlation_id`; the
+removed key is accepted and ignored rather than restored as domain identity.
+This compatibility rule avoids an eager rewrite of existing Journal data and
+does not define a general unknown-field or schema-versioning policy.
+
+## Explicit non-goals
+
+This decision does not:
+
+- change FSMSession identity ownership;
+- rename the shared Runtime `set_graph_metadata(thread_id:)` bridge;
+- remove Runtime-only `AgentInvocation#session_id`;
+- migrate `agent_invocation_id` parent references to `execution_id`
+  (subsequently decided by [ADR-022](022-agent-execution-parent-identity-and-runtime-routing-boundary.md));
+- redesign Tool / Approval Runtime routing;
+- remove `AgentExecutionActivation`;
+- implement EventLoop single-writer ownership;
+- implement recovery, fencing, or cross-process ownership.
+
+Those concerns belong to the subsequent Runtime identity / ownership change
+sets and compatibility gates.
+
+## Consequences
+
+### Positive
+
+- Agent and Workflow no longer overload the same generic `thread_id` term.
+- Arbitrary application session/correlation concepts are not elevated into the
+  Phronomy core identity catalog.
+- Tracing task correlation remains available without being confused with
+  lifecycle ownership.
+- Multi-Agent child execution no longer inherits an undefined generic identity.
+- The public contract and architecture vocabulary become purpose-specific.
+
+### Trade-offs
+
+- This is a pre-1.0 breaking API change.
+- Applications that used Agent `thread_id` / `InvocationContext#session_id`
+  must move correlation into application tracing/observability metadata or use
+  the actual purpose-specific domain identifier.
+- Legacy durable Journal data retains targeted backward-read compatibility;
+  broader codec/schema versioning policy remains a separate persistence decision.