ace-herdr 0.4.0 → 0.5.1

data/lib/ace/herdr/organisms/inbox_context_direct_effects.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+require_relative "../molecules/inbox_direct_effect_binding"
+require_relative "../molecules/inbox_direct_result"
+
+require_relative "../molecules/protected_native_control"
+
+module Ace
+  module Herdr
+    module Organisms
+      # Fixed methods on the same context admission and DeliveryRecord owner.
+      module InboxContextDirectEffects
+        def enqueue_context(operation_id:, key_generation:, event_id:, attempt_id:, reverse:, payload_bytes:, payload_sha256:, payload:, original:, peer:)
+          authorize!(peer, purpose: "enqueue")
+          binding = Molecules::InboxDirectEffectBinding.build(purpose: "enqueue", event_id: event_id,
+            attempt_id: attempt_id, key_generation: key_generation, original: original,
+            selection: {"reverse" => reverse, "payload_bytes" => payload_bytes, "payload_sha256" => payload_sha256})
+          unless payload.is_a?(String) && payload.bytesize == payload_bytes &&
+              payload.encoding == Encoding::UTF_8 && payload.valid_encoding? && !payload.include?("\0") &&
+              Digest::SHA256.hexdigest(payload) == payload_sha256
+            raise ValidationError, "direct enqueue payload differs"
+          end
+          selected = @keys.selected
+          original_query = direct_original_query!(operation_id, binding, selected, peer, payload_sha256: payload_sha256)
+          unless original_query.fetch("process_binding").values_at("session", "pane") == reverse.values_at("session", "pane")
+            raise ValidationError, "direct reverse address differs from original launch"
+          end
+          dispatch = false
+          transaction do |state|
+            operation = operation!(state, operation_id, peer)
+            unless operation.values_at("purpose", "event_id", "key_generation") == ["enqueue", event_id, key_generation] && operation.fetch("original") == original.merge("attempt_id" => attempt_id) &&
+                selected.fetch(:snapshot) == state.fetch("key")
+              raise ValidationError, "direct enqueue admission differs"
+            end
+            if operation["original_binding_digest"] && operation.fetch("original_binding_digest") != original_query.fetch("original_binding_digest")
+              raise ValidationError, "direct original launch record changed"
+            end
+            if operation["effect_binding"]
+              raise ValidationError, "direct enqueue input changed" unless operation.fetch("effect_binding") == binding
+              raise ValidationError, "direct enqueue issuer remains unresolved" if @effect_issuers.key?(operation_id) || operation.fetch("in_flight") == 1
+              direct_idle_readback!(state, operation)
+            else
+              raise ValidationError, "direct enqueue admission is uncertain" unless operation.fetch("in_flight").zero?
+              operation["original_binding_digest"] = original_query.fetch("original_binding_digest")
+              operation["effect_binding"] = binding
+              operation["in_flight"] = 1
+              operation["issuer_state"] = "running"
+              operation["issuer_epoch"] = @epoch
+              @effect_issuers[operation_id] = Thread.current
+              dispatch = true
+            end
+          end
+          box = source_inbox!(selected)
+          if dispatch
+            box.enqueue(event: event_id, attempt: attempt_id, ref: reverse, payload: payload, original_context: original, original_binding_digest: original_query.fetch("original_binding_digest"))
+            record_direct_return!(operation_id, peer, binding)
+          end
+          result = box.verify_direct_enqueue(binding)
+          if dispatch
+            transaction do |state|
+              operation = operation!(state, operation_id, peer)
+              unless operation["effect_binding"] == binding && @effect_issuers[operation_id].equal?(Thread.current) &&
+                  selected.fetch(:snapshot) == state.fetch("key")
+                raise ValidationError, "direct enqueue completion changed"
+              end
+              direct_idle_readback!(state, operation)
+              operation["in_flight"] = 0
+            end
+          end
+          immutable_effect(Molecules::InboxDirectResult.build(operation: "enqueue_context", record: result, admission_state: "idle"))
+        ensure
+          if dispatch
+            transaction { |_state| @effect_issuers.delete(operation_id) if @effect_issuers[operation_id].equal?(Thread.current) }
+          end
+        end
+
+        def deliver_context(operation_id:, key_generation:, event_id:, attempt_id:, expected_claim_generation:, original:, peer:)
+          authorize!(peer, purpose: "deliver")
+          binding = Molecules::InboxDirectEffectBinding.build(purpose: "deliver", event_id: event_id,
+            attempt_id: attempt_id, key_generation: key_generation, original: original,
+            selection: {"expected_claim_generation" => expected_claim_generation})
+          selected = @keys.selected
+          record = source_inbox!(selected).retained_status(event: event_id)
+          original_query = direct_original_query!(operation_id, binding, selected, peer, payload_sha256: record.fetch("payload_sha256"))
+          unless record.fetch("original_binding_digest") == original_query.fetch("original_binding_digest")
+            raise ValidationError, "direct retained original record differs"
+          end
+          dispatch = false
+          transaction do |state|
+            operation = operation!(state, operation_id, peer)
+            unless operation.values_at("purpose", "event_id", "key_generation") == ["deliver", event_id, key_generation] && operation.fetch("original") == original.merge("attempt_id" => attempt_id) &&
+                selected.fetch(:snapshot) == state.fetch("key")
+              raise ValidationError, "direct delivery admission differs"
+            end
+            direct_delivery_predecessors!(state, operation_id, event_id, key_generation)
+            if operation["original_binding_digest"] && operation.fetch("original_binding_digest") != original_query.fetch("original_binding_digest")
+              raise ValidationError, "direct original launch record changed"
+            end
+            if operation["effect_binding"]
+              raise ValidationError, "direct delivery input changed" unless operation.fetch("effect_binding") == binding
+              raise ValidationError, "direct delivery issuer remains live" if @effect_issuers.key?(operation_id)
+              # Unknown replay is observation only; it cannot become known idle.
+              direct_idle_readback!(state, operation) if operation.fetch("in_flight").zero?
+            else
+              raise ValidationError, "direct delivery admission is uncertain" unless operation.fetch("in_flight").zero?
+              source_inbox!(selected).verify_direct_delivery(binding)
+              operation["original_binding_digest"] = original_query.fetch("original_binding_digest")
+              operation["effect_binding"] = binding
+              operation["in_flight"] = 1
+              operation["issuer_state"] = "running"
+              operation["issuer_epoch"] = @epoch
+              @effect_issuers[operation_id] = Thread.current
+              dispatch = true
+            end
+          end
+          box = source_inbox!(selected)
+          if dispatch
+            transaction do |state|
+              operation = operation!(state, operation_id, peer)
+              unless operation["effect_binding"] == binding && operation["issuer_state"] == "running" &&
+                  @effect_issuers[operation_id].equal?(Thread.current)
+                raise ValidationError, "direct claim preparation ownership differs"
+              end
+              direct_delivery_predecessors!(state, operation_id, event_id, key_generation)
+              operation["admitted_claim"] = box.prepare_direct_delivery(event: event_id,
+                expected_claim_generation: expected_claim_generation, expected_attempt: attempt_id,
+                claim_owner: Digest::SHA256.hexdigest(JSON.generate([@context_id, operation_id])),
+                operation_id: operation_id, key_generation: key_generation, effect_binding: binding)
+            end
+            claim = transaction { |state| copy(operation!(state, operation_id, peer)["admitted_claim"]) }
+            unless claim && claim.fetch("kind") == "wake"
+              box.deliver(event: event_id, expected_claim_generation: expected_claim_generation,
+                expected_attempt: attempt_id, prepared_claim: claim && claim.slice("claim_generation", "claim_owner")) do |text|
+                native_binding = original_query.fetch("process_binding").merge("guarded_origin" => original_query.fetch("guarded_origin"))
+                direct_queue_control!(original_query).inbox_prompt(binding: native_binding, text: text)
+              end
+            end
+            direct_guarded_wake!(operation_id, peer, binding, claim, original_query, box) if claim
+            record_direct_return!(operation_id, peer, binding)
+          end
+          verified = box.verify_direct_delivery(binding)
+          transaction do |state|
+            operation = operation!(state, operation_id, peer)
+            unless operation["effect_binding"] == binding && selected.fetch(:snapshot) == state.fetch("key")
+              raise ValidationError, "direct delivery completion changed"
+            end
+            if dispatch && verified.fetch("idle") && @effect_issuers[operation_id].equal?(Thread.current)
+              direct_idle_readback!(state, operation)
+              operation["in_flight"] = 0
+            end
+            Molecules::InboxDirectResult.build(operation: "deliver_context", record: verified.fetch("record"),
+              admission_state: operation.fetch("in_flight").zero? ? "idle" : "unknown")
+          end
+        ensure
+          if dispatch
+            transaction { |_state| @effect_issuers.delete(operation_id) if @effect_issuers[operation_id].equal?(Thread.current) }
+          end
+        end
+
+        def status_context(event_id:, attempt_id:, original:, peer:)
+          grant = authorize!(peer)
+          unless (grant.fetch("purposes") & %w[enqueue deliver]).any?
+            raise ValidationError, "context event observation is unauthorized"
+          end
+          token!(event_id); token!(attempt_id)
+          Molecules::InboxDirectEffectBinding.original!(original)
+          context!(original.fetch("inbox_context_id"))
+          record = source_inbox!(@keys.selected).retained_status(event: event_id)
+          raise ValidationError, "context event attempt differs" unless record.fetch("attempt_id") == attempt_id && record.fetch("original_context") == original
+          immutable_effect(Molecules::InboxDirectResult.build(operation: "status_context", record: record))
+        end
+
+        private
+
+        # Remote canonical identity read occurs outside the store transaction.
+        # Both sides recheck the original durable admission/key before effects.
+        def direct_original_query!(operation_id, binding, selected, peer, payload_sha256:)
+          transaction do |state|
+            operation = operation!(state, operation_id, peer)
+            unless selected.fetch(:snapshot) == state.fetch("key") &&
+                operation.fetch("original") == binding.slice(*Molecules::InboxDirectEffectBinding::ORIGINAL_FIELDS, "attempt_id") &&
+                operation.values_at("purpose", "event_id") == binding.values_at("purpose", "event_id")
+              raise ValidationError, "original query admission differs"
+            end
+          end
+          result = @completion.original!(assignment_id: binding.fetch("assignment_id"), attempt_id: binding.fetch("attempt_id"),
+            event_id: binding.fetch("event_id"), inbox_context_id: binding.fetch("inbox_context_id"), purpose: binding.fetch("purpose"),
+            payload_sha256: payload_sha256)
+          unless result.slice(*Molecules::InboxDirectEffectBinding::ORIGINAL_FIELDS, "attempt_id", "event_id", "purpose") ==
+              binding.slice(*Molecules::InboxDirectEffectBinding::ORIGINAL_FIELDS, "attempt_id", "event_id", "purpose")
+            raise ValidationError, "original authority association differs"
+          end
+          result
+        rescue NoMethodError, KeyError, TypeError
+          raise ValidationError, "original authority identity is unavailable"
+        end
+
+        def direct_queue_control!(original)
+          native = original.fetch("native_binding")
+          server = native.fetch("server_identity")
+          mapping = {"worker_uid" => server.fetch("uid"), "worker_gid" => server.fetch("gid"), "worker_groups" => server.fetch("groups"),
+            "native" => original.fetch("native_channel").merge("server_identity" => server, "socket_identity" => native.fetch("socket_identity"))}
+          Molecules::ProtectedNativeControl.new(mapping: mapping, kernel: @kernel)
+        end
+
+        def direct_guarded_wake!(operation_id, peer, binding, claim, original, box)
+          return unless box.guarded_wake_pending?(event: binding.fetch("event_id"), binding: binding, claim: claim)
+          control = direct_queue_control!(original)
+          native_binding = original.fetch("process_binding").merge("guarded_origin" => original.fetch("guarded_origin"))
+          begin
+            control.prompt_preflight!(native_binding)
+          rescue Ace::Runtime::RuntimeUnavailableError
+            # This readonly preflight never entered notification IO. Pending
+            # stays positively unissued; a fresh explicit retry owns recovery.
+            return
+          end
+          issuing = transaction do |state|
+            operation = operation!(state, operation_id, peer)
+            unless operation["admitted_claim"] == claim && operation["effect_binding"] == binding &&
+                operation["issuer_state"] == "running" && @effect_issuers[operation_id].equal?(Thread.current) &&
+                operation.fetch("original_binding_digest") == original.fetch("original_binding_digest")
+              raise ValidationError, "guarded wake issuer changed"
+            end
+            direct_delivery_predecessors!(state, operation_id, binding.fetch("event_id"), operation.fetch("key_generation"))
+            box.prepare_guarded_wake(event: binding.fetch("event_id"), binding: binding, claim: claim, operation_id: operation_id)
+          end
+          return unless issuing
+          result = control.queue_wake(binding: native_binding)
+          transaction do |state|
+            operation = operation!(state, operation_id, peer)
+            unless operation["admitted_claim"] == claim && operation["effect_binding"] == binding &&
+                operation["issuer_state"] == "running" && @effect_issuers[operation_id].equal?(Thread.current)
+              raise ValidationError, "guarded wake finish admission changed"
+            end
+            box.finish_guarded_wake(event: binding.fetch("event_id"), binding: binding, claim: claim, issuing: issuing, result: result)
+          end
+        end
+
+        def record_direct_return!(operation_id, peer, binding)
+          transaction do |state|
+            operation = operation!(state, operation_id, peer)
+            unless operation["effect_binding"] == binding && operation["issuer_state"] == "running" &&
+                @effect_issuers[operation_id].equal?(Thread.current)
+              raise ValidationError, "direct issuer return ownership differs"
+            end
+            operation["issuer_state"] = "returned"
+          end
+        end
+
+        def direct_binding?(operation)
+          operation.dig("effect_binding", "schema") == Molecules::InboxDirectEffectBinding::SCHEMA
+        end
+
+        def direct_delivery_predecessors!(state, operation_id, event_id, key_generation)
+          state.fetch("operations").each do |id, other|
+            next if id == operation_id || other.fetch("event_id") != event_id || other.fetch("key_generation") != key_generation
+            if other.fetch("in_flight") == 1 || @effect_issuers.key?(id)
+              raise ValidationError, "direct delivery preceding issuer remains unresolved"
+            end
+          end
+        end
+
+        def direct_idle_readback!(state, operation)
+          selected = @keys.selected
+          raise ValidationError, "direct readback key changed" unless selected.fetch(:snapshot) == state.fetch("key")
+          binding = Molecules::InboxDirectEffectBinding.verify!(operation.fetch("effect_binding"), key_generation: operation.fetch("key_generation"))
+          box = source_inbox!(selected)
+          record = if binding.fetch("purpose") == "enqueue"
+            box.verify_direct_enqueue(binding)
+          else
+            claim = operation["admitted_claim"]
+            if claim && claim["kind"] == "wake"
+              operation_id = state.fetch("operations").find { |_id, retained| retained.equal?(operation) }&.first
+              box.verify_guarded_wake_admission!(binding: binding, claim: claim, operation_id: operation_id)
+            end
+            box.verify_direct_delivery(binding, require_idle: true).fetch("record")
+          end
+          unless record.fetch("original_binding_digest") == operation.fetch("original_binding_digest")
+            raise ValidationError, "direct readback original record changed"
+          end
+          record
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/organisms/inbox_context_effects.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../molecules/inbox_context_completion_client"
+
+module Ace
+  module Herdr
+    module Organisms
+      # Source effect methods on the same context owner and admission metadata.
+      module InboxContextEffects
+        SNAPSHOT_FIELDS = %w[event_id attempt_id payload_sha256 claim_generation state origin_target target binding].freeze
+
+        private
+
+        def source_inbox!(selected)
+          raise ValidationError, "fixed context Inbox owner is unavailable" unless @inbox.is_a?(Inbox)
+          @inbox
+        end
+
+        def immutable_effect(value)
+          case value
+          when Hash then value.to_h { |key, item| [key.dup.freeze, immutable_effect(item)] }.freeze
+          when Array then value.map { |item| immutable_effect(item) }.freeze
+          when String then value.dup.freeze
+          else value.freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/herdr/organisms/inbox_context_listener.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "inbox_context_server"
+require_relative "../molecules/inbox_context_service_configuration"
+
+module Ace
+  module Herdr
+    module Organisms
+      # Connection lifetimes never retire admission metadata. Stop prevents
+      # new ingress, then waits within one deadline for existing handlers.
+      class InboxContextListener
+        MAX_HANDLERS = 8
+        STOP_SECONDS = 35
+
+        def initialize(configuration:, server:, kernel: Ace::Runtime::Molecules::ProtectedLinux.new,
+          protection: Ace::Runtime::Molecules::ProtectedSocket, handler_dispatcher: nil)
+          unless configuration.is_a?(Molecules::InboxContextServiceConfiguration)
+            raise ValidationError, "context listener configuration is not held"
+          end
+          @configuration, @server, @kernel, @protection = configuration, server, kernel, protection
+          @handler_dispatcher = handler_dispatcher
+          @path = configuration.data.fetch("control_socket_path")
+          @credentials = configuration.data.fetch("owner_credentials")
+          @mutex, @handlers, @stopping = Mutex.new, {}, false
+        end
+
+        def serve
+          me = @kernel.capture(Process.pid)
+          unless me.values_at("uid", "gid", "groups") == @credentials.values_at("uid", "gid", "groups")
+            raise ValidationError, "context listener principal differs"
+          end
+          @kernel.live!(me)
+          @protection.root_path!(File.dirname(@path), directory: true, owner: @credentials.fetch("uid"))
+          verify_socket_traversal!
+          @lock = File.open("#{@path}.lock", File::RDWR | File::CREAT | File::NOFOLLOW | File::NONBLOCK, 0o600)
+          stat = @lock.stat
+          unless stat.file? && stat.uid == @credentials.fetch("uid") && stat.nlink == 1 && (stat.mode & 0o7777) == 0o600 &&
+              [stat.dev, stat.ino] == File.lstat("#{@path}.lock").then { |current| [current.dev, current.ino] } &&
+              @lock.flock(File::LOCK_EX | File::LOCK_NB)
+            raise ValidationError, "context listener lease differs or is held"
+          end
+          @lock.close_on_exec = true
+          remove_stale_endpoint!
+          @listener = UNIXServer.new(@path)
+          File.chown(nil, @configuration.data.fetch("socket_gid"), @path)
+          File.chmod(0o660, @path)
+          @identity = @protection.socket_identity(@path)
+          until stopping?
+            socket = @listener.accept
+            accepted_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 60
+            @mutex.synchronize do
+              if @stopping || @handlers.size >= MAX_HANDLERS
+                socket.close
+              else
+                gate = Queue.new
+                thread = Thread.new(socket, accepted_deadline) do |connection, operation_deadline|
+                  gate.pop
+                  begin
+                    if @handler_dispatcher
+                      @handler_dispatcher.call(deadline: operation_deadline) { @server.handle(connection) }
+                    else
+                      @server.handle(connection)
+                    end
+                  rescue ValidationError, Ace::Runtime::RuntimeUnavailableError, IOError, SystemCallError, Timeout::Error
+                    # Wire loss preserves the owner's retained operation state.
+                    nil
+                  ensure
+                    connection.close
+                    @mutex.synchronize { @handlers.delete(Thread.current) }
+                  end
+                end
+                @handlers[thread] = socket
+                gate << true
+              end
+            end
+          end
+        rescue IOError, Errno::EBADF
+          raise unless stopping?
+        ensure
+          stop if @listener
+          @listener&.close
+          remove_owned_endpoint!
+          @lock&.close
+        end
+
+        def stop(deadline: Process.clock_gettime(Process::CLOCK_MONOTONIC) + STOP_SECONDS)
+          unless deadline.is_a?(Numeric) && deadline.finite?
+            raise ValidationError, "context stop deadline differs"
+          end
+          threads = @mutex.synchronize do
+            @stop_deadline = @stop_deadline ? [@stop_deadline, deadline].min : deadline
+            @stopping = true
+            @listener&.close
+            @handlers.keys
+          end
+          threads.each do |thread|
+            remaining = @stop_deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break unless remaining.positive?
+            thread.join(remaining)
+          end
+          if @mutex.synchronize { !@handlers.empty? }
+            raise ValidationError, "context handlers remain unresolved at stop deadline"
+          end
+          true
+        end
+
+        def quiescent?
+          @mutex.synchronize { @handlers.empty? && (!@listener || @listener.closed?) }
+        end
+
+        private
+
+        def stopping? = @mutex.synchronize { @stopping }
+
+        def verify_socket_traversal!
+          parent = File.dirname(@path)
+          stat = File.lstat(parent)
+          unless stat.gid == @configuration.data.fetch("socket_gid") && (stat.mode & 0o7777) == 0o750
+            raise ValidationError, "context socket parent is not the exact shared traversal directory"
+          end
+          loop do
+            stat = File.lstat(parent)
+            unless stat.directory? && !stat.symlink? && @configuration.data.fetch("grants").all? { |grant|
+              bit = stat.uid == grant.fetch("uid") ? 0o100 : (grant.fetch("groups") + [grant.fetch("gid")]).include?(stat.gid) ? 0o010 : 0o001
+              grant.fetch("uid").zero? || (stat.mode & bit).positive?
+            }
+              raise ValidationError, "context caller cannot traverse its fixed socket ancestry"
+            end
+            break if parent == "/"
+            parent = File.dirname(parent)
+          end
+        end
+
+        def remove_stale_endpoint!
+          stat = File.lstat(@path)
+          raise ValidationError, "context endpoint differs" unless stat.socket? && stat.uid == @credentials.fetch("uid")
+          File.unlink(@path)
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def remove_owned_endpoint!
+          File.unlink(@path) if @identity && @protection.socket_identity(@path) == @identity
+        rescue Errno::ENOENT
+          nil
+        end
+      end
+    end
+  end
+end