phronomy 0.26.0 → 0.27.0

data/docs/migrations/shared-state-multi-agent.md

@@ -0,0 +1,44 @@
+# SharedState moves to MultiAgent
+
+This change applies to the architecture refactoring branch after core commit
+`aa9c3d53090bda4deb01b8cab16a43539b6b1deb`. Use the matching core and examples
+checkouts; the unchanged gem version number alone does not identify this API.
+
+| Previous Experimental API | API after this change |
+|---|---|
+| `Phronomy::Agent::SharedState` | `Phronomy::MultiAgent::SharedState` |
+| `Phronomy::Agent::SharedState::KnowledgeStore` | `Phronomy::MultiAgent::SharedState::KnowledgeStore` |
+
+The previous name is removed without an alias. Update superclass declarations
+and explicit constant references. For example:
+
+```ruby
+require "phronomy"
+
+class ResearchTeam < Phronomy::MultiAgent::SharedState
+  member Researcher
+  max_cycles 3
+end
+```
+
+Use the public application entry point `require "phronomy"`. The old internal
+file `phronomy/agent/shared_state.rb` is removed; arbitrary implementation-file
+requires are not a supported partial-loading API.
+
+The DSL, `invoke(input, config: {})` signature, sequential order, shared findings,
+termination rules and `{output:, cycles:, terminated_by:}` result remain the same.
+`config:` remains accepted but is not forwarded to member invocations. Timeout
+is checked between complete cycles and does not cancel an active Agent.
+
+Set `PHRONOMY_PATH` to the matching local core checkout before running
+`bundle install` or the examples verification. Example `22_shared_state` now
+uses the new superclass, and the examples API preflight rejects mismatched core.
+
+No saved-record or SQL schema migration is required. Do not rewrite the existing
+`Phronomy::Agent::SharedState::Instrumented/` generated definition ID: it is
+deliberately preserved together with instrumentation version 1. It is not an
+alias for the removed Ruby constant. The in-memory KnowledgeStore still lasts
+for one invocation only.
+
+See [ADR-053](../decisions/053-shared-state-coordination-ownership.md) for the
+ownership and compatibility decision.

data/docs/migrations/storage-backend-composition.md

@@ -0,0 +1,117 @@
+# Storage Backend composition migration
+
+Historical migration step. Its old raw SPI surface is superseded by the
+[neutral Storage SPI 2 migration](neutral-storage-spi.md); use that guide for the
+current backend contract.
+
+
+This change targets the `refactor/architecture` branch after `1b481f6`, with
+shared value operations already owned by `Values::Immutable`.
+It replaces the Beta Backend SPI; the gem version and persisted record formats
+are not changed by this branch-only refactoring package.
+
+## Application construction
+
+An isolated in-memory domain is now constructed with:
+
+```ruby
+require "phronomy"
+
+persistence = Phronomy::Persistence.in_memory
+Phronomy.configure { |config| config.persistence = persistence }
+```
+
+An explicitly selected raw backend is composed once:
+
+```ruby
+require "phronomy"
+
+backend = Phronomy::Storage::Backends::InMemory.new
+persistence = Phronomy::Persistence.new(backend: backend)
+Phronomy.configure { |config| config.persistence = persistence }
+```
+
+Use the same `persistence` instance wherever one storage/ownership domain is
+required. Constructing several facades over one physical backend does not create
+independent data, and their object identities are distinct for callers that use
+Persistence identity to determine a domain. `persistence.backend` exposes the
+selected raw backend for backend-specific administration such as accessing its
+connection pool. Ordinary domain reads and writes still use `persistence`.
+
+## Replaced API
+
+| Previous API | Replacement |
+|---|---|
+| `Persistence::InMemory.new` | `Persistence.in_memory` |
+| Backend subclass of `Persistence` | Backend subclass of `Storage::Backend`, or the same raw protocol |
+| `Persistence.new` with eight raw repository keyword arguments | `Persistence.new(backend: raw_backend)` |
+| Backend `super` with eight repositories | The same arguments passed to `Storage::Backend#initialize` |
+| `Persistence#build_transaction_view` | A raw `Storage::Repositories` view yielded by the backend |
+| `Persistence::DurableRecord` | `Storage::DurableRecord` |
+| `Persistence::ConflictError` / `NotFoundError` / `SerializationError` / `UnsupportedBackendError` | The same names under `Storage` |
+| `Persistence::REQUIRED_CAPABILITIES` | `Storage::Backend::REQUIRED_CAPABILITIES` |
+
+The previous constants/helper/constructor are removed. Rescue the new storage
+error constants. The public `Phronomy::AgentBusyError` admission exception remains.
+This is a source/API migration, not a persisted payload migration.
+
+## SQL implementation changes
+
+A raw SQL backend implements `capabilities`, `transaction`, and
+`assert_agent_watermark!`, and supplies all eight raw repositories to the common
+Backend constructor. It exchanges `Storage::DurableRecord` and explicit ID,
+revision, position, and admission metadata. It does not decode domain types.
+
+In its transaction implementation:
+
+1. Check out a connection and open the database transaction as before.
+2. Bind contents, agents, journals, executions, workflow_states, handoff_states,
+   teams, team_executions, and the watermark object to that same connection.
+3. Construct `Storage::Repositories` with those eight keyword arguments and
+   `watermark:`; yield this raw view inside the database transaction block.
+4. Return the block result; propagate failures through the existing transaction
+   rollback path. Keep the existing handling of indeterminate commit outcomes.
+
+`Persistence#transaction` constructs the corresponding domain facades inside
+that block. SQL code no longer calls `build_transaction_view` or private
+`PersistenceComposition::Repositories` or domain repository wrappers. Application/bootstrap code creates the raw SQL backend,
+then passes it to `Persistence.new(backend:)`.
+
+The SQLite and PostgreSQL implementations in `phronomy-examples` at `231d253`
+use the previous SPI and require this migration. Do not use their unchanged
+sources with the new core. Keep this branch's API change separate from a release
+until the applications/backends to be shipped with it have also migrated.
+
+## Validation
+
+Use the existing explicitly loaded shared contract suite with a composed
+`persistence` value. All eight repositories must still commit or roll back
+together. Validate root and transaction repository binding, CAS/admission and
+watermark checks, record round trips, and codec failure rollback. Perform actual
+SQL tests with the backend's supported database and driver versions; an
+in-memory success does not prove SQL transaction/concurrency behavior.
+
+## Execution constraint errors (ADR-043)
+
+Raw `Storage::Backend` execution repositories must report
+`Storage::ActiveExecutionConflictError`, a `Storage::ConflictError` subtype, when
+an existing nonterminal execution prevents another admission or an idle-only
+operation for that owner. Update the same constraint branches in `save` if the
+backend already checks them. Do not convert unrelated identity/revision failures.
+
+The Agent and Team repository facades translate this subtype into the existing
+`Phronomy::AgentBusyError` while preserving its message and cause. A transaction
+still sees the exception before commit. Public Persistence/Agent/Team callers
+keep their previous busy exception; raw backend callers must update their rescue.
+
+Apply the new core before the migrated SQLite/PostgreSQL sources. Both examples
+require the new storage constant; for coordinated source development set
+`PHRONOMY_PATH` to the updated core checkout before resolving/running their
+bundles. An unchanged legacy backend remains usable through the domain facade
+because its old `AgentBusyError` is passed through, but it does not satisfy the
+new raw conformance checks. No fallback constant aliases are supplied.
+
+Run `a Persistence backend` from `phronomy/testing/persistence_contract`; it now
+includes `storage execution constraint notifications` for both raw execution
+repositories. Keep running the domain repository suites and backend concurrency
+and rollback tests. No schema or serialized data migration is required.

data/docs/migrations/storage-transaction-boundaries.md

@@ -0,0 +1,74 @@
+# Storage transaction boundaries (Refactor 34)
+
+Historical migration step. Its old raw SPI surface is superseded by the
+[neutral Storage SPI 2 migration](neutral-storage-spi.md); use that guide for the
+current backend contract.
+
+
+Update core and the SQLite/PostgreSQL reference adapters together. No data
+migration is required. The public method signatures, eight repository accessors,
+required capability keys and stored record formats are unchanged.
+
+## Explicit nested calls
+
+Nested `Backend#transaction` and `Persistence#transaction` calls on the same
+backend and synchronous execution context now have savepoint semantics.
+
+```ruby
+persistence.transaction do |outer|
+  outer.contents.put_text("keep if outer succeeds")
+  begin
+    persistence.transaction do |inner|
+      inner.contents.put_text("discard on inner failure")
+      raise "inner failure"
+    end
+  rescue RuntimeError
+    # Inner changes have already been rolled back. Re-read conditions needed
+    # for subsequent work through the valid outer scope.
+    outer.contents.put_text("outer may continue")
+  end
+end
+```
+
+Earlier SQL reference versions joined the outer scope. Catching the inner error
+could preserve inner writes. Such writes are now rolled back. A successful inner
+call does not commit independently; failure of the outer call rolls back both.
+The same exception object is propagated after rollback, including
+`ActiveRecord::Rollback`, which ActiveRecord itself normally consumes. Catch
+that exception outside the Storage/Persistence block if continued execution is
+intended. No separate database connection is introduced.
+
+## Invalid Journal batches and database failures
+
+The SQL references now validate and serialize every record and normalize the
+expected position before the first write. An invalid second record cannot leave
+the first inserted with an unchanged Journal head. Record IDs from a rejected
+input batch can be retried with valid data.
+
+This is an input-validation guarantee. A database failure after writing must
+escape the current transaction scope. To continue outer work, establish an
+explicit inner scope before the operation, and catch outside that inner scope.
+Do not catch and ignore database errors inside the failed scope. Unknown commit
+outcomes still require existing reconciliation rules, not blind retries.
+
+## Active Agent execution updates
+
+InMemory now enforces the same active-owner exclusion during update as SQL.
+Trying to reactivate an Agent execution while a different execution for that
+Agent is active raises `Storage::ActiveExecutionConflictError` at the raw boundary
+and does not advance the revision or replace the record. The domain-facing
+repository retains its existing error translation. Team terminal execution
+reactivation remains forbidden.
+
+## Backend authors and remaining migration
+
+Run `phronomy/testing/persistence_contract`, including `a Persistence backend`,
+against each real backend. Explicit nested calls must preserve block results,
+exception identity, inner rollback and outer atomicity across repositories.
+SQL integrations additionally exercise physical constraints, concurrent writers,
+connection failure and durable reload; mocked connection responses do not cover
+those guarantees.
+
+Records/Streams/Blobs, failed-view enforcement and explicit non-local block-exit
+handling are later S2b work. Do not use `return` / `break` / `throw` as portable
+commit controls in the current SPI. See [ADR-057](../decisions/057-storage-transaction-boundaries.md).