ace-hitl 0.12.0 → 0.13.0

data/lib/ace/hitl/lifecycle/service.rb

@@ -48,6 +48,8 @@ module Ace
           @proposal_clock = proposal_clock
           @max_connections = MAX_CONNECTIONS
           @connections = 0
+          @handler_threads = []
+          @handler_sockets = []
           @connections_mutex = Mutex.new
           @stopping = false
           @server = nil
@@ -57,8 +59,9 @@ module Ace
 
         # Serve until #stop. Installs TERM/INT handlers for a clean
         # shutdown that unlinks the socket file.
-        def run
+        def run(on_ready: nil)
           prepare!
+          on_ready.call if on_ready
           if Thread.current == Thread.main
             %i[TERM INT].each do |signal|
               trap(signal) { stop }
@@ -86,12 +89,21 @@ module Ace
               end
               next
             end
-            Thread.new(connection) do |socket|
-              begin
-                serve_connection(socket)
-              ensure
-                @connections_mutex.synchronize { @connections -= 1 }
+            @connections_mutex.synchronize do
+              @handler_sockets << connection
+              @handler_threads.reject! { |thread| !thread.alive? }
+              thread = Thread.new(connection) do |socket|
+                begin
+                  serve_connection(socket)
+                ensure
+                  @connections_mutex.synchronize do
+                    @connections -= 1
+                    @handler_sockets.delete(socket)
+                  end
+                end
               end
+              thread.report_on_exception = false
+              @handler_threads << thread
             end
           end
         ensure
@@ -152,6 +164,16 @@ module Ace
         end
 
         def shutdown!
+          stop
+          @connections_mutex.synchronize { @handler_sockets.dup }.each { |socket| socket.close rescue nil }
+          failures = []
+          @connections_mutex.synchronize { @handler_threads.dup }.each do |thread|
+            begin
+              thread.join
+            rescue Exception => error
+              failures << error
+            end
+          end
           begin
             @server&.close
           rescue SystemCallError, IOError
@@ -167,6 +189,7 @@ module Ace
             @endpoint_lock = nil
           end
           log("stopped")
+          raise failures.first unless failures.empty?
         end
 
         # The socket's parent directory is part of the trust boundary: it
@@ -213,7 +236,7 @@ module Ace
             policy: @policy,
             identity: peer,
             vault: @vault,
-            proposal_clock: @proposal_clock
+            proposal_clock: @proposal_clock, stopping: -> { @stopping }
           )
         end
 
@@ -232,18 +255,18 @@ module Ace
           case op
           when "ping" then {"pong" => true}
           when "proposal-create" then store.proposal_create(**symbolize(params))
-          when "proposal-show" then store.proposal_show(required(params, "id"), history_after: params.fetch("history_after", 0))
-          when "proposal-revise" then store.proposal_revise(required(params, "id"), expected_revision: required(params, "expected_revision"),
+          when "proposal-show" then store.proposal_show(required(params, "id"), project: required(params, "project"), history_after: params.fetch("history_after", 0))
+          when "proposal-revise" then store.proposal_revise(required(params, "id"), project: required(params, "project"), expected_revision: required(params, "expected_revision"),
             operation_id: required(params, "operation_id"), document: required(params, "document"))
           when "proposal-ack"
-            store.proposal_acknowledge(required(params, "id"), submitted_at: required(params, "submitted_at"))
+            store.proposal_acknowledge(required(params, "id"), project: required(params, "project"), submitted_at: required(params, "submitted_at"))
           when "proposal-reply"
-            store.proposal_reply(required(params, "id"), answer: required(params, "answer"),
+            store.proposal_reply(required(params, "id"), project: required(params, "project"), answer: required(params, "answer"),
               received_at: required(params, "received_at"), sequence: required(params, "sequence"))
           when "proposal-reconcile"
-            store.proposal_reconcile(required(params, "id"), checkpoint: required(params, "checkpoint"))
+            store.proposal_reconcile(required(params, "id"), project: required(params, "project"), checkpoint: required(params, "checkpoint"))
           when "proposal-wake" then store.proposal_wake(project: required(params, "project"), after: params["after"])
-          when "proposal-due" then store.proposal_due(after: params["after"])
+          when "proposal-due" then store.proposal_due(project: required(params, "project"), after: params["after"])
           when "proposal-history" then store.proposal_history(project: required(params, "project"),
             query: params.fetch("query", ""), after: params["after"])
           when "create" then store.create(**symbolize(params))

data/lib/ace/hitl/lifecycle/service_publication_binding.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+require_relative "binding"
+require "json"
+
+module Ace
+  module Hitl
+    module Lifecycle
+      # Constructed beside the same-process authority, never from wire data.
+      # The selector is routing data; only the authority's held callback can
+      # admit a store transition for the original receiver process.
+      class ServicePublicationBinding < Binding
+        FIELDS = %w[schema mapping_id assignment_id attempt_id request_id claim_binding input_digest
+          candidate_generation head challenge_digest].freeze
+
+        def initialize(ordinary:, authority:, kernel:)
+          @ordinary, @authority, @kernel = ordinary, authority, kernel
+        end
+
+        def validate_request(**params)
+          deny_executor_ordinary!(params.fetch(:project), params[:caller_pid])
+          @ordinary.validate_request(**params)
+        end
+
+        def reverse_address(**params)
+          @ordinary.reverse_address(**params)
+        end
+
+        def with_active(**params, &block)
+          @ordinary.with_active(**params, &block)
+        end
+
+        def proposal_journal(project:)
+          @ordinary.proposal_journal(project: project)
+        end
+
+        def proposal_projects
+          @ordinary.proposal_projects
+        end
+
+        def with_publication!(binding:, identity:, assignment:, attempt:, project:, otp:, original_peer: nil, requester_required: true)
+          unless binding.is_a?(Hash) && binding.keys.sort == FIELDS.sort &&
+              binding["schema"] == "ace.hitl-publication-binding/v1" &&
+              binding["assignment_id"] == assignment && binding["attempt_id"] == attempt &&
+              %w[mapping_id assignment_id attempt_id request_id].all? { |key| binding[key].is_a?(String) && binding[key].match?(/\A[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}\z/) } &&
+              %w[claim_binding input_digest challenge_digest].all? { |key| binding[key].is_a?(String) && binding[key].match?(/\A[0-9a-f]{64}\z/) } &&
+              binding["head"].is_a?(String) && binding["head"].match?(/\A[0-9a-f]{40}\z/) &&
+              binding["candidate_generation"].is_a?(Integer) && binding["candidate_generation"].positive? &&
+              otp.is_a?(Hash) && otp["operation"] == "publish" && otp["input_digest"] == binding["input_digest"]
+            raise BindingError, "publication HITL selector differs"
+          end
+          caller = requester_required ? actual_peer!(identity) : original_peer
+          raise BindingError, "publication original receiver differs" if original_peer && caller != original_peer
+          @authority.with_publication_hitl!(binding: binding, project: project, peer: caller) do |selection|
+            unless selection.fetch("challenge_ref") == otp["result_ref"] && selection.fetch("executor_process_binding") == caller
+              raise BindingError, "publication challenge or receiver differs"
+            end
+            yield selection
+          end
+        rescue Ace::Assign::Error, Ace::Runtime::RuntimeUnavailableError => e
+          raise BindingError, "publication authority unavailable (#{e.class.name})"
+        end
+
+        def verify_publication_requester!(identity:, original_peer:)
+          raise BindingError, "publication original receiver differs" unless actual_peer!(identity) == original_peer
+          true
+        end
+
+        private
+
+        def actual_peer!(identity)
+          unless identity.respond_to?(:pid) && identity.pid.is_a?(Integer) && identity.pid.positive?
+            raise BindingError, "publication kernel peer is unavailable"
+          end
+          peer = @kernel.capture(identity.pid)
+          unless peer["uid"] == identity.uid && peer["gid"] == identity.gid
+            raise BindingError, "publication kernel credentials differ"
+          end
+          @kernel.live!(peer)
+          peer
+        end
+
+        def deny_executor_ordinary!(project, pid)
+          unless pid.is_a?(Integer) && pid.positive?
+            raise BindingError, "HITL kernel requester is unavailable"
+          end
+          peer = @kernel.capture(pid)
+          @kernel.live!(peer)
+          if @authority.publication_executor_identity?(project: project, uid: peer.fetch("uid"))
+            raise BindingError, "executor cannot select an ordinary worker HITL request"
+          end
+        rescue Ace::Assign::Error, Ace::Runtime::RuntimeUnavailableError => error
+          raise BindingError, "HITL kernel requester unavailable (#{error.class.name})"
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/lifecycle/store.rb

@@ -79,7 +79,7 @@ module Ace
 
         def initialize(root:, binding:, policy: AccessPolicy.new,
           identity: Identity, ownership: AtomicJson::DEFAULT_OWNERSHIP,
-          poll_seconds: CONSUME_POLL_SECONDS, vault: :file, proposal_clock: -> { Time.now.utc })
+          poll_seconds: CONSUME_POLL_SECONDS, vault: :file, proposal_clock: -> { Time.now.utc }, stopping: -> { false })
           raise ArgumentError, "a binding policy is required (fail closed without one)" unless binding
           raise ArgumentError, "an access policy is required (fail closed without one)" unless policy
 
@@ -91,6 +91,7 @@ module Ace
           @poll_seconds = poll_seconds
           @vault = vault == :file ? OtpVault::FileVault : vault
           @proposal_clock = proposal_clock
+          @stopping = stopping
         end
 
         # ---- requester side ------------------------------------------------
@@ -101,16 +102,39 @@ module Ace
         # validates its binding — unknown identity/authority is an
         # error, never permission.
         def create(id:, attempt:, plan:, question:, ace_hitl_id:, project: "ace", harness: "lab-admin",
-          assignment:, kind: "text", options: [], effect: nil, otp: nil)
+          assignment:, kind: "text", options: [], effect: nil, otp: nil, publication_binding: nil)
           raise StateError, "proposal kind must use proposal_create" if kind == "proposal"
           value = prepare_request(id: id, attempt: attempt, plan: plan, question: question,
             ace_hitl_id: ace_hitl_id, project: project, harness: harness, assignment: assignment,
-            kind: kind, options: options, effect: effect, otp: otp)
-          persist_request(value)
+            kind: kind, options: options, effect: effect, otp: otp, publication_binding: publication_binding)
+          return persist_request(value) unless value["publication_binding"]
+          with_request_lock(value.fetch("id")) do
+            with_live_authority!(value, requester: @identity.username) do
+              if value["publication_binding"]
+                if load_terminal(value.fetch("id"))
+                  raise StateError, "publication HITL id is already terminal"
+                end
+                duplicate = request_path(value.fetch("id")).exist? && load_request(value.fetch("id"))
+                if duplicate
+                  unless duplicate.slice("publication_binding", "publication_requester_peer", "otp") == value.slice("publication_binding", "publication_requester_peer", "otp")
+                    raise StateError, "publication HITL id has different binding"
+                  end
+                  return {"id" => duplicate.fetch("id"), "requested" => true, "replay" => true, "envelope" => duplicate.fetch("envelope")}
+                end
+                requests_dir.glob("*.json").each do |path|
+                  existing = AtomicJson.read(path)
+                  if existing["publication_binding"] == value["publication_binding"]
+                    raise StateError, "publication challenge already has an active HITL request"
+                  end
+                end
+              end
+              persist_request_locked!(value)
+            end
+          end
         end
 
         def prepare_request(id:, attempt:, plan:, question:, ace_hitl_id:, project: "ace", harness: "lab-admin",
-          assignment:, kind: "text", options: [], effect: nil, otp: nil)
+          assignment:, kind: "text", options: [], effect: nil, otp: nil, publication_binding: nil)
           requester = @identity.username
           request_id = safe_id(id)
           validate_binding_ids!(assignment, attempt)
@@ -143,7 +167,13 @@ module Ace
             challenge = normalize_otp_challenge!(otp)
           end
 
-          reverse = validate_request_binding(assignment, attempt, project, requester)
+          if publication_binding
+            raise StateError, "publication HITL must be OTP" unless kind == "otp"
+            publication_binding = JSON.parse(JSON.generate(publication_binding))
+            reverse = nil
+          else
+            reverse = validate_request_binding(assignment, attempt, project, requester)
+          end
 
           value = {
             "id" => request_id,
@@ -161,6 +191,7 @@ module Ace
             "created_at" => Time.now.to_i
           }
           value["otp"] = challenge if challenge
+          value["publication_binding"] = publication_binding if publication_binding
           Effects.validate_declaration!(effect) if effect
           value["effect"] = Effects.normalized_declaration(effect) if effect
           value["incarnation"] = SecureRandom.hex(8)
@@ -182,6 +213,10 @@ module Ace
         private :prepare_request
 
         def persist_request(value)
+          with_request_lock(value.fetch("id")) { persist_request_locked!(value) }
+        end
+
+        def persist_request_locked!(value)
           request_id = value.fetch("id")
           attempt = value.fetch("attempt")
           request_path = requests_dir.join("#{request_id}.json")
@@ -197,7 +232,7 @@ module Ace
           rescue Errno::EEXIST
             raise StateError, "HITL request already exists"
           end
-          initialize_projection!(value)
+          initialize_projection_locked!(value)
           {
             "id" => request_id,
             "assignment" => value["assignment"],
@@ -207,7 +242,7 @@ module Ace
           }
         end
 
-        private :persist_request
+        private :persist_request, :persist_request_locked!
 
         # Non-secret request facts for the requester of record (or the
         # transport). Never carries answer content.
@@ -217,7 +252,7 @@ module Ace
             terminal = load_terminal(request_id)
             if terminal
               gate_read_access!(terminal)
-              return terminal.slice("id", "assignment", "attempt", "project", "requester", "sensitive", "envelope", "state", "native_delivery", "effect_receipt_ref")
+              return terminal.slice("id", "assignment", "attempt", "project", "requester", "sensitive", "envelope", "state", "native_delivery", "effect_receipt_ref", "publication_binding", "publication_requester_peer", "otp")
                 .merge("kind" => terminal.dig("envelope", "kind"))
             end
           end
@@ -235,13 +270,15 @@ module Ace
             "options" => value["options"],
             "plan" => value["plan"],
             "otp" => value["otp"],
+            "publication_binding" => value["publication_binding"],
+            "publication_requester_peer" => value["publication_requester_peer"],
             "requester" => value["requester"],
             "envelope" => value["envelope"],
             "state" => public_state(request_id, value),
             "effect_receipt_ref" => effect_receipt_ref(value),
             "effect" => value["effect_state"]
           }
-          facts["proposal"] = proposal_for_request!(request_id) if value["kind"] == "proposal"
+          facts["proposal"] = proposal_for_request!(request_id, project: value.fetch("project")) if value["kind"] == "proposal"
           facts
         end
 
@@ -273,6 +310,7 @@ module Ace
           verify_operation!(value, operation)
           deadline = timeout.positive? ? Time.now.to_i + timeout : nil
           loop do
+            raise TransportError, "HITL boundary is stopping; request remains pending" if @stopping.call
             answer = nil
             with_request_lock(request_id) do
               begin
@@ -294,6 +332,7 @@ module Ace
                 verify_native_consumer!(value) if native_delivery
                 verify_operation!(value, operation)
                 verify_otp_deadline!(value)
+                raise TransportError, "HITL boundary is stopping; request remains pending" if @stopping.call
                 answer = read_answer(value)
                 unless answer
                   next
@@ -354,11 +393,19 @@ module Ace
             unless @identity.username == value["requester"].to_s
               raise PermissionError, "only the requesting role can cancel this request"
             end
-            commit_terminal!(value, "cancelled", audit)
-            update_public(value, "cancelled", audit: audit)
-            @vault.discard(self, value)
-            remove_request(value, keep_public: true)
-            locked_value = value
+            cancel = lambda do
+              requester_gate!(value)
+              commit_terminal!(value, "cancelled", audit)
+              update_public(value, "cancelled", audit: audit)
+              @vault.discard(self, value)
+              remove_request(value, keep_public: true)
+              locked_value = value
+            end
+            if value["publication_binding"]
+              with_live_authority!(value, requester: @identity.username, &cancel)
+            else
+              cancel.call
+            end
           end
           {
             "id" => request_id,
@@ -625,19 +672,18 @@ module Ace
         # lock first and already delivered can never be regressed to
         # "created" — a current-incarnation projection is left untouched.
         def initialize_projection!(value)
-          request_id = safe_id(value["id"].to_s)
-          with_request_lock(request_id) do
-            current = AtomicJson.read(public_path(request_id))
-            predecessor = current.nil? || current["incarnation"] != value["incarnation"]
-            if predecessor
-              public_path(request_id).unlink if public_path(request_id).exist?
-              effects_dir.join("#{request_id}.json").unlink if effects_dir.join("#{request_id}.json").exist?
-              # A new incarnation supersedes the predecessor's terminal
-              # receipt: idempotent replays describe THIS lifecycle only
-              # (spec 8wq.t.34i).
-              terminals_dir.join("#{request_id}.json").unlink if terminals_dir.join("#{request_id}.json").exist?
-              update_public(value, "created")
-            end
+          with_request_lock(safe_id(value.fetch("id"))) { initialize_projection_locked!(value) }
+        end
+
+        def initialize_projection_locked!(value)
+          request_id = safe_id(value.fetch("id"))
+          current = AtomicJson.read(public_path(request_id))
+          predecessor = current.nil? || current["incarnation"] != value["incarnation"]
+          if predecessor
+            public_path(request_id).unlink if public_path(request_id).exist?
+            effects_dir.join("#{request_id}.json").unlink if effects_dir.join("#{request_id}.json").exist?
+            terminals_dir.join("#{request_id}.json").unlink if terminals_dir.join("#{request_id}.json").exist?
+            update_public(value, "created")
           end
           nil
         end
@@ -722,7 +768,7 @@ module Ace
 
         def verify_native_consumer!(value)
           raise StateError, "OTP requires protected local consume" if value["sensitive"] == true
-          reverse = @binding.reverse_address(attempt: value["attempt"],
+          reverse = @binding.reverse_address(assignment: value["assignment"], project: value["project"], attempt: value["attempt"],
             caller_pid: @identity.respond_to?(:pid) ? @identity.pid : nil)
           unless reverse && reverse == value.dig("envelope", "reverse")
             raise BindingError, "native delivery requires the exact original requester process"
@@ -730,7 +776,8 @@ module Ace
         end
 
         def validate_binding_ids!(assignment, attempt)
-          unless Kinds::COMPACT_ID.match?(assignment.to_s) && Kinds::COMPACT_ID.match?(attempt.to_s)
+          unless Kinds::COMPACT_ID.match?(assignment.to_s) &&
+              (Kinds::COMPACT_ID.match?(attempt.to_s) || Kinds::PROTECTED_ATTEMPT_ID.match?(attempt.to_s))
             raise StateError, "HITL request requires the exact managed assignment and attempt ids"
           end
         end
@@ -783,10 +830,16 @@ module Ace
           unless @identity.username == value["requester"].to_s
             raise PermissionError, "only the requesting role can consume this answer"
           end
+          if value["publication_binding"]
+            @binding.verify_publication_requester!(identity: @identity, original_peer: value.fetch("publication_requester_peer"))
+          end
         end
 
         def gate_read_access!(value)
-          return if @identity.username == value["requester"].to_s
+          if @identity.username == value["requester"].to_s
+            requester_gate!(value)
+            return
+          end
 
           require_transport!("read", value)
         end
@@ -829,6 +882,7 @@ module Ace
             raise PermissionError, "only the requesting role can #{operation == "cancelled" ? "cancel" : "consume"} this request"
           end
 
+          requester_gate!(terminal) if terminal["publication_binding"]
           case terminal["state"]
           when "cancelled"
             return replayed_cancel(request_id, terminal) if operation == "cancelled"
@@ -889,6 +943,9 @@ module Ace
             "effect_receipt_ref" => effect_receipt_ref(value),
             "at" => Time.now.to_i
           }
+          %w[publication_binding publication_requester_peer otp].each do |key|
+            record[key] = value[key] if value.key?(key)
+          end
           record["answer"] = extra[:answer] if extra[:answer]
           record["native_delivery"] = true if extra[:native_delivery]
           record["audit"] = extra["audit"] if extra["audit"]
@@ -907,11 +964,22 @@ module Ace
         # the request stays pending and the classified error propagates
         # for retry (review 8x32r9b0).
         def with_live_authority!(value, requester:)
-          @binding.with_active(
-            assignment: value["assignment"], attempt: value["attempt"],
-            project: value["project"], requester: requester
-          ) do
-            yield
+          if value["publication_binding"]
+            unless @binding.respond_to?(:with_publication!)
+              raise BindingError, "publication HITL source binding is unavailable"
+            end
+            @binding.with_publication!(binding: value.fetch("publication_binding"), identity: @identity,
+              assignment: value.fetch("assignment"), attempt: value.fetch("attempt"), project: value.fetch("project"),
+              otp: value.fetch("otp"), original_peer: value["publication_requester_peer"],
+              requester_required: @identity.username == value.fetch("requester")) do |selection|
+              value["publication_requester_peer"] ||= JSON.parse(JSON.generate(selection.fetch("executor_process_binding")))
+              yield
+            end
+          else
+            @binding.with_active(
+              assignment: value["assignment"], attempt: value["attempt"],
+              project: value["project"], requester: requester
+            ) { yield }
           end
         rescue EndedAttemptError
           update_public(value, "cancelled")

data/lib/ace/hitl/live_client.rb

@@ -8,8 +8,9 @@ require_relative "providers/lab"
 module Ace
   module Hitl
     # Explicit in-process client. The scoped service owns answer availability
-    # and business callbacks; Herdr owns queue submission, wake and signed
-    # consumption proof. A watcher lives only as long as its requesting agent.
+    # and business callbacks; Herdr owns delivery to the selected live terminal.
+    # A watcher lives only as long as its requesting agent. Delivery status is
+    # read from that original Inbox owner, never a duplicate recovery projection.
     class LiveClient
       def initialize(boundary: nil, coordinator: nil, inbox: nil, root: Dir.pwd)
         @boundary = boundary
@@ -63,9 +64,6 @@ module Ace
         event = event_id(envelope)
         queued = inbox.enqueue(event: event, attempt: envelope["attempt_id"], ref: reverse, payload: answer,
           managed_envelope: delivery, expected_target: target)
-        # A signed supersession authorizes an explicit reconciliation retry,
-        # not another ordinary delivery/watch call.
-        return queued if queued["state"] == "queued" && queued.dig("reconciliation", "outcome") == "superseded"
         coordinator.bind_inbox(attempt_id: envelope["attempt_id"], event_id: event, inbox: inbox)
         inbox.deliver(event: event)
       ensure
@@ -84,36 +82,20 @@ module Ace
           next facts unless facts["native_delivery"] == true
           envelope = envelope_for(facts, facts["id"])
           delivery = delivery_status(envelope)
-          next if delivery["state"] == "completed"
+          next if delivery["state"] == "delivered"
           facts.merge("delivery" => delivery)
         end
       end
 
-      # Only the existing signed verifier + accepted attempt registration may
-      # settle uncertainty. Explicit retry is admitted solely by verified
-      # supersession, including its verified replacement native target.
-      def reconcile(request:, receipt_path:, retry_delivery: false)
-        facts = boundary.read(request)
-        envelope = envelope_for(facts, request)
-        event = event_id(envelope)
-        result = coordinator.reconcile_inbox(attempt_id: envelope["attempt_id"], event_id: event,
-          receipt_path: receipt_path, inbox: inbox)
-        if retry_delivery && result["state"] == "queued" && !result["reconciliation_refusal"] &&
-            result.dig("reconciliation", "outcome") == "superseded"
-          return inbox.deliver(event: event)
-        end
-        result
-      end
-
       private
 
       def delivery_status(envelope)
         event = event_id(envelope)
-        # A requester-writable raw delivery state cannot supply consumption
-        # authority. Recovery's journal-attributed public view owns that fact.
-        snapshot = coordinator.recovery_snapshot(envelope["assignment_id"])
-        snapshot.fetch("inbox_events").find { |record| record["event_id"] == event } ||
-          {"event_id" => event, "state" => "unknown"}
+        # This is transport history from its original owner, not proof that
+        # an agent read an answer or a cached view of the current terminal.
+        inbox.status(event: event)
+      rescue Ace::Herdr::Organisms::Inbox::MissingEventError
+        {"event_id" => event, "state" => "not-submitted"}
       end
 
       def envelope_for(result, request)

data/lib/ace/hitl/providers/lab/assignment_binding.rb

@@ -23,13 +23,13 @@ module Ace
 
           def validate_request(assignment:, attempt:, project:, requester:, caller_pid: nil)
             with_verified(assignment, attempt, project, requester) do
-              reverse_address(attempt: attempt, caller_pid: caller_pid)
+              reverse_address(assignment: assignment, attempt: attempt, project: project, caller_pid: caller_pid)
             end
           end
 
           # Read-only owner verification can run inside an already-held
           # assignment exclusion without reacquiring that exclusion.
-          def reverse_address(attempt:, caller_pid:)
+          def reverse_address(assignment:, attempt:, project:, caller_pid:)
             unless caller_pid.is_a?(Integer) && caller_pid.positive?
               raise Lifecycle::BindingError, "kernel requester process identity is unavailable"
             end
@@ -45,10 +45,17 @@ module Ace
             with_verified(assignment, attempt, project, requester) { yield }
           end
 
-          def proposal_journal
+          def proposal_journal(project:)
+            unless project.is_a?(String) && !project.empty?
+              raise Lifecycle::BindingError, "proposal requires an explicit project"
+            end
             coordinator.send(:journal_for)
           end
 
+          def proposal_projects
+            coordinator.send(:journal_for).proposals.map { |record| record.fetch("project_id") }.uniq.sort
+          end
+
           private
 
           def with_verified(assignment_id, attempt_id, project_id, requester)