phronomy 0.26.0 → 0.27.0

data/lib/phronomy/testing/persistence_contract/an_execution_repository.rb

@@ -40,7 +40,7 @@ RSpec.shared_examples "an Execution repository" do
   it "raises NotFoundError for a missing execution" do
     expect do
       execution_repository.load("missing-#{SecureRandom.uuid}")
-    end.to raise_error(Phronomy::Persistence::NotFoundError)
+    end.to raise_error(Phronomy::Storage::NotFoundError)
   end
 
   it "rejects a duplicate execution_id" do
@@ -49,7 +49,7 @@ RSpec.shared_examples "an Execution repository" do
 
     expect do
       execution_repository.create_active(execution)
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Storage::ConflictError)
   end
 
   it "admits at most one active or suspended execution for one Agent" do
@@ -107,7 +107,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: updated
       )
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Storage::ConflictError)
   end
 
   it "rejects an execution identity mismatch" do
@@ -131,7 +131,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: other
       )
-    end.to raise_error(Phronomy::Persistence::SerializationError)
+    end.to raise_error(Phronomy::Storage::SerializationError)
   end
 
   it "requires execution revision to advance exactly once" do
@@ -149,7 +149,7 @@ RSpec.shared_examples "an Execution repository" do
         expected_revision: 0,
         execution: skipped
       )
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Storage::ConflictError)
   end
 
   it "lists active executions for one Agent" do
@@ -179,7 +179,7 @@ RSpec.shared_examples "an Execution repository" do
 
     expect do
       execution_repository.load(execution.execution_id)
-    end.to raise_error(Phronomy::Persistence::NotFoundError)
+    end.to raise_error(Phronomy::Storage::NotFoundError)
   end
 
   it "deletes all executions for one Agent without deleting other Agents' executions" do

data/lib/phronomy/testing/persistence_contract/coordination_repositories.rb

@@ -43,14 +43,14 @@ RSpec.shared_examples "a Handoff state repository" do
     persistence.handoff_states.save(value.main_agent_id, expected_revision: 1, state: updated)
     expect do
       persistence.handoff_states.save(value.main_agent_id, expected_revision: 1, state: updated)
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Storage::ConflictError)
     expect(persistence.handoff_states.load(value.main_agent_id).handoff_revision).to eq(2)
   end
 
   it "rejects a snapshot for a different routing anchor" do
     expect do
       persistence.handoff_states.save("other", expected_revision: nil, state: coordination_handoff)
-    end.to raise_error(Phronomy::Persistence::SerializationError)
+    end.to raise_error(Phronomy::Storage::SerializationError)
   end
 end
 
@@ -60,7 +60,7 @@ RSpec.shared_examples "a Team repository" do
   it "round-trips a Team lineage and rejects duplicate creation" do
     persistence.teams.create(coordination_team)
     expect(persistence.teams.load(coordination_team.team_id).to_h).to eq(coordination_team.to_h)
-    expect { persistence.teams.create(coordination_team) }.to raise_error(Phronomy::Persistence::ConflictError)
+    expect { persistence.teams.create(coordination_team) }.to raise_error(Phronomy::Storage::ConflictError)
   end
 
   it "rejects a stale Team revision" do
@@ -69,11 +69,11 @@ RSpec.shared_examples "a Team repository" do
     persistence.teams.save(coordination_team.team_id, expected_revision: 0, root: updated)
     expect do
       persistence.teams.save(coordination_team.team_id, expected_revision: 0, root: updated)
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Storage::ConflictError)
   end
 
   it "raises NotFoundError for an absent Team" do
-    expect { persistence.teams.load(SecureRandom.uuid) }.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect { persistence.teams.load(SecureRandom.uuid) }.to raise_error(Phronomy::Storage::NotFoundError)
   end
 end
 
@@ -100,11 +100,11 @@ RSpec.shared_examples "a Team execution repository" do
     expect(persistence.team_executions.list("other-team")).to be_empty
     expect do
       persistence.team_executions.save(completed.team_execution_id, expected_revision: 0, execution: completed)
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Storage::ConflictError)
     expect do
       persistence.team_executions.save(completed.team_execution_id, expected_revision: 1,
         execution: completed.with(status: "active", phase: "coordinator"))
-    end.to raise_error(Phronomy::Persistence::ConflictError)
+    end.to raise_error(Phronomy::Storage::ConflictError)
   end
 
   it "rolls the new three repositories back with the existing transaction domain" do
@@ -129,7 +129,7 @@ RSpec.shared_examples "a Team execution repository" do
     expect(persistence.teams.load(coordination_team.team_id).team_revision).to eq(0)
     expect(persistence.handoff_states.load(handoff.main_agent_id)).to be_nil
     expect(persistence.team_executions.list(coordination_team.team_id)).to be_empty
-    expect { persistence.agents.load(root_id) }.to raise_error(Phronomy::Persistence::NotFoundError)
+    expect { persistence.agents.load(root_id) }.to raise_error(Phronomy::Storage::NotFoundError)
     expect(persistence.executions.list(root_id)).to be_empty
     expect(persistence.workflow_states.load(root_id)).to be_nil
     expect(persistence.contents.exist?(content_ref)).to be(false)

data/lib/phronomy/testing/persistence_contract/neutral_storage_primitives.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+# This same opaque-record suite runs against InMemory, SQLite and PostgreSQL.
+RSpec.shared_examples "neutral storage primitives" do
+  let(:raw_backend) { persistence.backend }
+  let(:raw_view) { raw_backend.view }
+  let(:raw_schema) { Phronomy::Agent::Persistence::StorageSchema }
+  let(:raw_record) { Phronomy::Storage::DurableRecord.new(record_type: "unrelated.envelope", format_version: "0.1", payload: {"status" => "ignored"}) }
+  let(:raw_owner) { "owner-#{SecureRandom.uuid}" }
+  let(:raw_key) { "key-#{SecureRandom.uuid}" }
+  let(:raw_records) { raw_view.records(raw_schema::EXECUTIONS) }
+  let(:raw_stream) { raw_view.streams(raw_schema::JOURNAL) }
+  let(:raw_blobs) { raw_view.blobs(Phronomy::ContentStore::StorageSchema::CONTENTS) }
+
+  def raw_insert(key = raw_key, active: true, owner: raw_owner)
+    raw_records.insert(key: key, revision: 0, attributes: {owner: owner, active: active}, record: raw_record)
+  end
+
+  before do
+    raw_view.records(raw_schema::ROOTS).insert(key: raw_owner, revision: 7, attributes: {}, record: raw_record)
+  end
+
+  it "keeps payload opaque and returns independent immutable entries" do
+    inserted = raw_insert
+    loaded = raw_records.fetch(raw_key)
+    expect(loaded).not_to equal(inserted)
+    expect(loaded.record).not_to equal(inserted.record)
+    expect(loaded.to_h.except(:record)).to eq(inserted.to_h.except(:record))
+    expect(loaded).to be_frozen
+    expect(loaded.attributes).to be_frozen
+    expect(loaded.record.payload).to eq("status" => "ignored")
+  end
+
+  it "reports a named conditional unique constraint separately from primary identity" do
+    raw_insert
+    expect { raw_insert("other") }.to raise_error(Phronomy::Storage::UniqueConstraintError) { |error|
+      expect(error.resource).to eq(raw_schema::EXECUTIONS.id)
+      expect(error.constraint).to eq(:one_active_owner)
+    }
+    expect { raw_insert }.to raise_error(Phronomy::Storage::ConflictError) { |error|
+      expect(error).not_to be_a(Phronomy::Storage::UniqueConstraintError)
+    }
+  end
+
+  it "checks revision before active-owner exclusion and retains failed writes" do
+    raw_insert
+    expect do
+      raw_records.replace(key: raw_key, expected_revision: 9, next_revision: 10,
+        attributes: {owner: raw_owner, active: false}, record: raw_record)
+    end.to raise_error(Phronomy::Storage::ConflictError)
+    expect(raw_records.fetch(raw_key).revision).to eq(0)
+  end
+
+  it "checks immutable owner and explicit expected attributes" do
+    raw_insert
+    expect do
+      raw_records.replace(key: raw_key, expected_revision: 0, next_revision: 1,
+        attributes: {owner: "another", active: true}, record: raw_record)
+    end.to raise_error(Phronomy::Storage::ConflictError)
+    expect do
+      raw_records.replace(key: raw_key, expected_revision: 0, next_revision: 1,
+        expected_attributes: {active: false}, attributes: {owner: raw_owner, active: true}, record: raw_record)
+    end.to raise_error(Phronomy::Storage::ConflictError)
+    expect(raw_records.fetch(raw_key).revision).to eq(0)
+  end
+
+  it "keeps active semantics outside Records while enforcing the declared unique rule" do
+    raw_insert(active: false)
+    raw_insert("competitor")
+    expect do
+      raw_records.replace(key: raw_key, expected_revision: 0, next_revision: 1,
+        attributes: {owner: raw_owner, active: true}, record: raw_record)
+    end.to raise_error(Phronomy::Storage::UniqueConstraintError)
+    raw_records.replace(key: "competitor", expected_revision: 0, next_revision: 1,
+      attributes: {owner: raw_owner, active: false}, record: raw_record)
+    expect(raw_records.replace(key: raw_key, expected_revision: 0, next_revision: 1,
+      attributes: {owner: raw_owner, active: true}, record: raw_record).revision).to eq(1)
+  end
+
+  it "orders equality-index pages by UTF-8 bytes with an exclusive cursor" do
+    keys = ["z", "é", "Z", "a"]
+    keys.each { |key| raw_insert(key, active: false) }
+    sorted = keys.sort_by(&:b)
+    first = raw_records.scan(index: :owner, equals: {owner: raw_owner}, limit: 2)
+    rest = raw_records.scan(index: :owner, equals: {owner: raw_owner}, after: first.last.key)
+    expect((first + rest).map(&:key)).to eq(sorted)
+    expect(raw_records.scan(index: :owner_active, equals: {owner: raw_owner, active: true})).to be_empty
+  end
+
+  it "validates index shape, limits, attributes and revisions before writing" do
+    expect { raw_records.scan(index: :missing, equals: {}) }.to raise_error(ArgumentError)
+    expect { raw_records.scan(index: :owner, equals: {active: true}) }.to raise_error(ArgumentError)
+    expect { raw_records.scan(index: :owner, equals: {owner: raw_owner}, limit: 0) }.to raise_error(ArgumentError)
+    expect { raw_records.insert(key: raw_key, revision: -1, attributes: {owner: raw_owner, active: true}, record: raw_record) }.to raise_error(ArgumentError)
+    expect { raw_records.insert(key: raw_key, revision: 0, attributes: {owner: raw_owner, active: "true"}, record: raw_record) }.to raise_error(ArgumentError)
+    expect(raw_records.read(raw_key)).to be_nil
+  end
+
+  it "requires a parent anchor for child creation, stream append and bulk deletion" do
+    expect { raw_insert(owner: "missing-parent") }.to raise_error(Phronomy::Storage::NotFoundError)
+    expect { raw_stream.append(stream: "missing-parent", expected_head: 0, entries: []) }.to raise_error(Phronomy::Storage::NotFoundError)
+    expect { raw_records.delete_matching(index: :owner, equals: {owner: "missing-parent"}) }.to raise_error(Phronomy::Storage::NotFoundError)
+    expect(raw_records.read(raw_key)).to be_nil
+  end
+
+  it "separates optional reads, required fetches and revision-checked deletion" do
+    expect(raw_records.read(raw_key)).to be_nil
+    expect { raw_records.fetch(raw_key) }.to raise_error(Phronomy::Storage::NotFoundError)
+    expect { raw_records.delete(key: raw_key, expected_revision: 0) }.to raise_error(Phronomy::Storage::ConflictError)
+    expect(raw_records.delete(key: raw_key)).to be_nil
+    raw_insert
+    expect { raw_records.delete(key: raw_key, expected_revision: 1) }.to raise_error(Phronomy::Storage::ConflictError)
+    raw_records.delete(key: raw_key, expected_revision: 0)
+    expect(raw_records.read(raw_key)).to be_nil
+  end
+
+  it "deletes only the equality-index matches" do
+    raw_insert(active: false)
+    raw_insert("active")
+    raw_records.delete_matching(index: :owner_active, equals: {owner: raw_owner, active: false})
+    expect(raw_records.read(raw_key)).to be_nil
+    expect(raw_records.fetch("active").attributes[:active]).to be(true)
+  end
+
+  it "keeps ordered stream positions, entry IDs and head in one atomic append" do
+    entries = %w[first second].map { |id| Phronomy::Storage::Entry::Append.new(id: id, record: raw_record) }
+    appended = raw_stream.append(stream: raw_owner, expected_head: 0, entries: entries)
+    expect(appended.map(&:position)).to eq([1, 2])
+    expect(raw_stream.head(stream: raw_owner)).to eq(2)
+    expect(raw_stream.read(stream: raw_owner, after: 1, limit: 1).map(&:id)).to eq(["second"])
+    expect { raw_stream.append(stream: raw_owner, expected_head: 2, entries: [entries.first]) }.to raise_error(Phronomy::Storage::ConflictError)
+    expect(raw_stream.head(stream: raw_owner)).to eq(2)
+    expect(raw_stream.read(stream: raw_owner).map(&:id)).to eq(%w[first second])
+  end
+
+  it "checks the head for an empty append and validates duplicate IDs before writing" do
+    expect(raw_stream.append(stream: raw_owner, expected_head: 0, entries: [])).to be_empty
+    expect { raw_stream.append(stream: raw_owner, expected_head: 1, entries: []) }.to raise_error(Phronomy::Storage::ConflictError)
+    entry = Phronomy::Storage::Entry::Append.new(id: "same", record: raw_record)
+    expect { raw_stream.append(stream: raw_owner, expected_head: 0, entries: [entry, entry]) }.to raise_error(Phronomy::Storage::ConflictError)
+    expect(raw_stream.head(stream: raw_owner)).to eq(0)
+  end
+
+  it "deletes a stream's entries and head so identities and positions can be reused" do
+    entries = [Phronomy::Storage::Entry::Append.new(id: "reusable", record: raw_record)]
+    raw_stream.append(stream: raw_owner, expected_head: 0, entries: entries)
+    raw_stream.delete(stream: raw_owner)
+    expect(raw_stream.head(stream: raw_owner)).to eq(0)
+    expect(raw_stream.read(stream: raw_owner)).to be_empty
+    expect(raw_stream.append(stream: raw_owner, expected_head: 0, entries: entries).first.position).to eq(1)
+  end
+
+  it "uses arbitrary blob keys, preserves binary bytes and retains first metadata" do
+    bytes = "\x00\xffbinary".b
+    first = raw_blobs.put_if_absent(key: raw_key, bytes: bytes, attributes: {canonicalization_version: 1})
+    second = raw_blobs.put_if_absent(key: raw_key, bytes: bytes, attributes: {canonicalization_version: 99})
+    expect(first.attributes).to eq(second.attributes)
+    expect(raw_blobs.fetch(raw_key).bytes).to eq(bytes)
+    expect { raw_blobs.put_if_absent(key: raw_key, bytes: "other", attributes: {canonicalization_version: 1}) }.to raise_error(Phronomy::Storage::BlobConflictError)
+    expect(raw_blobs.fetch(raw_key).bytes).to eq(bytes)
+  end
+
+  it "evaluates guarded revision, stream head and no-rows conditions atomically" do
+    guard = Phronomy::Storage::GuardRef.new(resource: raw_schema::ROOTS, key: raw_owner)
+    revision = Phronomy::Storage::Condition::RevisionIs.new(resource: raw_schema::ROOTS, key: raw_owner, expected: 7)
+    head = Phronomy::Storage::Condition::StreamHeadIs.new(resource: raw_schema::JOURNAL, stream: raw_owner, expected: 0)
+    idle = Phronomy::Storage::Condition::NoRows.new(resource: raw_schema::EXECUTIONS, index: :owner_active, equals: {owner: raw_owner, active: true})
+    expect(raw_view.check!(guards: [guard], conditions: [revision, head, idle])).to be(true)
+    expect { raw_view.check!(guards: [], conditions: [head]) }.to raise_error(ArgumentError)
+    raw_insert
+    expect { raw_view.check!(guards: [guard], conditions: [idle]) }.to raise_error(Phronomy::Storage::ConditionFailedError) { |error| expect(error.condition).to equal(idle) }
+  end
+
+  it "rejects a retained bound view and retained handle after commit" do
+    saved_view = saved_records = nil
+    raw_backend.transaction { |view|
+      saved_view = view
+      saved_records = view.records(raw_schema::EXECUTIONS)
+    }
+    expect { saved_view.records(raw_schema::EXECUTIONS) }.to raise_error(Phronomy::Storage::TransactionError)
+    expect { saved_records.read(raw_key) }.to raise_error(Phronomy::Storage::TransactionError)
+    expect(raw_records.read(raw_key)).to be_nil
+  end
+
+  it "rejects a retained bound handle after rollback" do
+    handle = nil
+    expect do
+      raw_backend.transaction { |view|
+        handle = view.records(raw_schema::EXECUTIONS)
+        raise "abort"
+      }
+    end.to raise_error("abort")
+    expect { handle.read(raw_key) }.to raise_error(Phronomy::Storage::TransactionError)
+  end
+
+  it "rejects use of a bound view from another thread" do
+    raw_backend.transaction do |view|
+      result = Thread.new do
+        view.records(raw_schema::EXECUTIONS).read(raw_key)
+      rescue => error
+        error
+      end.value
+      expect(result).to be_a(Phronomy::Storage::TransactionError)
+      expect(view.records(raw_schema::EXECUTIONS).read(raw_key)).to be_nil
+    end
+  end
+
+  it "routes cached root handles into the current transaction and rolls back their writes" do
+    handle = raw_records
+    expect do
+      raw_backend.transaction do
+        handle.insert(key: raw_key, revision: 0, attributes: {owner: raw_owner, active: true}, record: raw_record)
+        raise "rollback"
+      end
+    end.to raise_error("rollback")
+    expect(handle.read(raw_key)).to be_nil
+  end
+
+  it "marks a failed physical scope unusable even when the operation error is caught" do
+    expect do
+      raw_backend.transaction do |view|
+        handle = view.records(raw_schema::EXECUTIONS)
+        handle.insert(key: raw_key, revision: 0, attributes: {owner: raw_owner, active: true}, record: raw_record)
+        expect { handle.insert(key: "collision", revision: 0, attributes: {owner: raw_owner, active: true}, record: raw_record) }.to raise_error(Phronomy::Storage::UniqueConstraintError)
+        expect { handle.read(raw_key) }.to raise_error(Phronomy::Storage::TransactionError)
+      end
+    end.to raise_error(Phronomy::Storage::TransactionError)
+    expect(raw_records.read(raw_key)).to be_nil
+  end
+
+  [:break, :throw, :return].each do |exit_kind|
+    it "rolls back a non-local #{exit_kind} instead of committing" do
+      operation = lambda do
+        case exit_kind
+        when :break
+          raw_backend.transaction {
+            raw_insert
+            break :escaped
+          }
+        when :throw
+          catch(:escape) {
+            raw_backend.transaction {
+              raw_insert
+              throw :escape
+            }
+          }
+        when :return
+          returner = -> {
+            raw_backend.transaction {
+              raw_insert
+              return :escaped
+            }
+          }
+          returner.call
+        end
+      end
+      expect { operation.call }.to raise_error(Phronomy::Storage::TransactionError)
+      expect(raw_records.read(raw_key)).to be_nil
+    end
+  end
+end

data/lib/phronomy/testing/persistence_contract/storage_transaction_boundaries.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+RSpec.shared_examples "storage transaction boundaries" do
+  [:backend, :persistence].each do |entry_point|
+    context "through #{entry_point} transactions" do
+      def transaction_contents(view)
+        view.is_a?(Phronomy::Storage::View) ? Phronomy::ContentStore::StoredContents.new(view) : view.contents
+      end
+
+      let(:transaction_service) { (entry_point == :backend) ? persistence.backend : persistence }
+
+      it "rolls back a failed inner scope and re-raises the same error before the outer scope continues" do
+        outer_id = inner_id = later_id = nil
+        workflow_id = "nested-#{SecureRandom.uuid}"
+        failure = RuntimeError.new("inner failure")
+
+        result = transaction_service.transaction do |outer|
+          outer_id = transaction_contents(outer).put_text("outer-#{workflow_id}")
+          expect do
+            transaction_service.transaction do |inner|
+              inner_id = transaction_contents(inner).put_text("inner-#{workflow_id}")
+              if entry_point == :backend
+                inner.records(Phronomy::WorkflowStorageSchema::STATES).insert(key: workflow_id,
+                  revision: 1, attributes: {}, record: Phronomy::Storage::DurableRecord.new(
+                    record_type: "opaque.transaction", format_version: "0.1", payload: {"value" => "inner"}
+                  ))
+              else
+                inner.workflow_states.save(workflow_id,
+                  expected_revision: nil, snapshot: {fields: {value: "inner"}, phase: "pause"})
+              end
+              raise failure
+            end
+          end.to raise_error { |error| expect(error).to equal(failure) }
+          expect(transaction_contents(outer).exist?(outer_id)).to be(true)
+          expect(transaction_contents(outer).exist?(inner_id)).to be(false)
+          expect(persistence.backend.view.records(Phronomy::WorkflowStorageSchema::STATES).read(workflow_id)).to be_nil
+          later_id = transaction_contents(outer).put_text("later-#{workflow_id}")
+          :outer_result
+        end
+
+        expect(result).to eq(:outer_result)
+        expect(persistence.contents.exist?(outer_id)).to be(true)
+        expect(persistence.contents.exist?(later_id)).to be(true)
+        expect(persistence.contents.exist?(inner_id)).to be(false)
+        expect(persistence.backend.view.records(Phronomy::WorkflowStorageSchema::STATES).read(workflow_id)).to be_nil
+      end
+
+      it "commits both scopes on normal completion and returns their block values" do
+        outer_id = inner_id = nil
+        result = transaction_service.transaction do |outer|
+          outer_id = transaction_contents(outer).put_text("outer-#{SecureRandom.uuid}")
+          inner_result = transaction_service.transaction do |inner|
+            inner_id = transaction_contents(inner).put_text("inner-#{SecureRandom.uuid}")
+            :inner_result
+          end
+          expect(inner_result).to eq(:inner_result)
+          :outer_result
+        end
+        expect(result).to eq(:outer_result)
+        expect(persistence.contents.exist?(outer_id)).to be(true)
+        expect(persistence.contents.exist?(inner_id)).to be(true)
+      end
+
+      it "rolls back successful inner writes when the outer scope fails" do
+        outer_id = inner_id = nil
+        expect do
+          transaction_service.transaction do |outer|
+            outer_id = transaction_contents(outer).put_text("outer-#{SecureRandom.uuid}")
+            result = transaction_service.transaction do |inner|
+              inner_id = transaction_contents(inner).put_text("inner-#{SecureRandom.uuid}")
+              :inner_result
+            end
+            expect(result).to eq(:inner_result)
+            expect(transaction_contents(outer).exist?(inner_id)).to be(true)
+            raise "outer failure"
+          end
+        end.to raise_error("outer failure")
+        expect(persistence.contents.exist?(outer_id)).to be(false)
+        expect(persistence.contents.exist?(inner_id)).to be(false)
+      end
+
+      it "rolls back both scopes when an inner error escapes the outer scope" do
+        outer_id = inner_id = nil
+        expect do
+          transaction_service.transaction do |outer|
+            outer_id = transaction_contents(outer).put_text("outer-#{SecureRandom.uuid}")
+            transaction_service.transaction do |inner|
+              inner_id = transaction_contents(inner).put_text("inner-#{SecureRandom.uuid}")
+              raise "uncaught inner failure"
+            end
+          end
+        end.to raise_error("uncaught inner failure")
+        expect(persistence.contents.exist?(outer_id)).to be(false)
+        expect(persistence.contents.exist?(inner_id)).to be(false)
+      end
+    end
+  end
+
+  it "validates every stream entry before writing any part of a batch" do
+    backend = persistence.backend
+    schema = Phronomy::Agent::Persistence::StorageSchema
+    owner_id = "batch-#{SecureRandom.uuid}"
+    record = Phronomy::Storage::DurableRecord.new(record_type: "opaque.transaction", format_version: "0.1", payload: {})
+    backend.view.records(schema::ROOTS).insert(key: owner_id, revision: 0, attributes: {}, record: record)
+    valid = Phronomy::Storage::Entry::Append.new(id: "first", record: record)
+    content_id = nil
+    backend.transaction do |view|
+      content_id = persistence.contents.put_text("retained-#{owner_id}")
+      stream = view.streams(schema::JOURNAL)
+      expect { stream.append(stream: owner_id, expected_head: 0, entries: [valid, Object.new]) }
+        .to raise_error(Phronomy::Storage::SerializationError)
+      expect(stream.head(stream: owner_id)).to eq(0)
+      expect(stream.read(stream: owner_id)).to be_empty
+    end
+    expect(persistence.contents.exist?(content_id)).to be(true)
+    entries = backend.view.streams(schema::JOURNAL).append(stream: owner_id, expected_head: 0,
+      entries: [valid, Phronomy::Storage::Entry::Append.new(id: "second", record: record)])
+    expect(entries.map(&:position)).to eq([1, 2])
+    expect(entries.map { |entry| entry.record.payload }).to eq([{}, {}])
+  end
+end

data/lib/phronomy/testing/persistence_contract.rb

@@ -30,6 +30,8 @@ module Phronomy
         "a Handoff state repository",
         "a Team repository",
         "a Team execution repository",
+        "neutral storage primitives",
+        "storage transaction boundaries",
         "a Persistence backend"
       ].freeze
     end
@@ -41,6 +43,8 @@ require_relative "persistence_contract/an_agent_repository"
 require_relative "persistence_contract/a_journal_repository"
 require_relative "persistence_contract/an_execution_repository"
 require_relative "persistence_contract/a_workflow_state_repository"
+require_relative "persistence_contract/neutral_storage_primitives"
+require_relative "persistence_contract/storage_transaction_boundaries"
 require_relative "persistence_contract/a_persistence_backend"
 
 require_relative "persistence_contract/coordination_repositories"

data/lib/phronomy/tool/contract/tool_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../../common/error"
+
+module Phronomy
+  class ToolError < Error; end
+end

data/lib/phronomy/tools/agent.rb

@@ -51,7 +51,7 @@ module Phronomy
           # The child Agent owns its own FSMSession/EventLoop lifecycle; this
           # method only returns its completion handle and performs a short map.
           klass.define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
-            persistence = Phronomy::Persistence::InMemory.new
+            persistence = Phronomy::Persistence.in_memory
             agent = agent_class.create(persistence: persistence)
             task_config = (config || {}).dup
             if cancellation_token && !task_config[:cancellation_token]

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.26.0"
+  VERSION = "0.27.0"
 end

data/lib/phronomy/{workflow.rb → workflow/execution/workflow.rb}

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 require_relative "workflow_runner"
-require_relative "runnable"
+require_relative "../../engine/runnable"
 
 module Phronomy
   # StateChart-style Workflow definition DSL.
   class Workflow
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     include Phronomy::Runnable
 
     def self.define(context_class, persistence: nil, &block)
@@ -72,8 +76,6 @@ module Phronomy
     public
 
     class Builder
-      FINISH = Phronomy::WorkflowRunner::FINISH
-
       def initialize(context_class, persistence: nil)
         @context_class = context_class
         @persistence = persistence
@@ -119,7 +121,7 @@ module Phronomy
       # They may start asynchronous work and register listeners, but returning
       # Phronomy::TaskResult is an error; completion must arrive as a later event.
       def transition(from:, to:, guard: nil, on: nil, action: nil)
-        destination = (to == :__finish__) ? FINISH : to
+        destination = (to == :__finish__) ? FSMProtocol::FINISH : to
         @transitions << {
           from: from,
           to: destination,
@@ -184,7 +186,7 @@ module Phronomy
 
         undefined_targets = @transitions
           .map { |transition| transition[:to] }
-          .reject { |target| target == FINISH } - all_states
+          .reject { |target| target == FSMProtocol::FINISH } - all_states
         unless undefined_targets.empty?
           raise ArgumentError,
             "Workflow transition(s) reference undefined state(s): " \
@@ -205,7 +207,7 @@ module Phronomy
           current = queue.shift
           @transitions.each do |transition|
             next unless transition[:from] == current
-            next if transition[:to] == FINISH
+            next if transition[:to] == FSMProtocol::FINISH
             next if reachable.include?(transition[:to])
 
             reachable.add(transition[:to])

data/lib/phronomy/{workflow_context.rb → workflow/execution/workflow_context.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../engine/concurrency/worker_input_restricted"
+
 module Phronomy
   # Module for defining Workflow context data.
   #
@@ -12,6 +14,8 @@ module Phronomy
   # evaluation, return a replacement WorkflowContext, or return +:consume+ to
   # discard a stale/unrelated event without firing a transition.
   module WorkflowContext
+    include Phronomy::Concurrency::WorkerInputRestricted
+
     def self.included(base)
       base.extend(ClassMethods)
       base.instance_variable_set(:@fields, {})

data/lib/phronomy/workflow/execution/workflow_context_ownership_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../../common/error"
+
+module Phronomy
+  class WorkflowContextOwnershipError < Error; end
+end