ace-hitl 0.17.0 → 0.23.2

data/lib/ace/hitl/proposals/evaluator.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Ace
-  module Hitl
-    module Proposals
-      # Authenticated proposer wake. The existing Hermes actor performs
-      # reconciliation under its own transport identity after polling.
-      class Evaluator
-        def initialize(boundary:, project:)
-          @boundary, @project = boundary, project
-        end
-
-        def call
-          results = []
-          after = nil
-          loop do
-            page = @boundary.proposal_wake(project: @project, after: after)
-            results.concat(page.fetch("items"))
-            cursor = page.fetch("next")
-            break unless cursor
-            raise Lifecycle::TransportError, "proposal cursor did not advance" unless cursor.is_a?(String) && (!after || cursor > after)
-            after = cursor
-          end
-          results
-        end
-      end
-    end
-  end
-end

data/lib/ace/hitl/proposals/policy.rb

@@ -1,127 +0,0 @@
-# frozen_string_literal: true
-
-require "json"
-require "digest"
-require "time"
-require "ace/hitl/contract/secret_gate"
-
-module Ace
-  module Hitl
-    module Proposals
-      # HITL owns decisions. This policy never claims or executes an effect.
-      module Policy
-        WINDOW = 16 * 60 * 60
-        APPROVED = %w[approved-explicitly approved-by-silence].freeze
-        REQUIRED = %w[operation target candidate_head input_digest context options recommendation prerequisites].freeze
-
-        module_function
-
-        def document(value)
-          data = JSON.parse(JSON.generate(value))
-          unless data.is_a?(Hash) && (REQUIRED - data.keys).empty? &&
-              (data.keys - REQUIRED - ["rationale"]).empty?
-            raise Lifecycle::StateError, "proposal fields differ from proposal/v1"
-          end
-          unless data["operation"].is_a?(String) && data["operation"].match?(/\A[a-z][a-z0-9-]{0,63}\z/) &&
-              data["candidate_head"].is_a?(String) && data["candidate_head"].match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/) &&
-              data["input_digest"].is_a?(String) && data["input_digest"].match?(/\A[0-9a-f]{64}\z/)
-            raise Lifecycle::StateError, "proposal must bind exact operation, candidate head and input digest"
-          end
-          target = data["target"]
-          unless target.is_a?(Hash) && (target.keys - %w[resource artifact_digest]).empty? &&
-              target["resource"].is_a?(String) && target["resource"].match?(/\A[a-zA-Z0-9_.:\/-]{1,256}\z/) &&
-              (!target["artifact_digest"] || (target["artifact_digest"].is_a?(String) &&
-                target["artifact_digest"].match?(/\A[0-9a-f]{64}\z/)))
-            raise Lifecycle::StateError, "proposal target must name exact resource and optional artifact digest"
-          end
-          target["artifact_digest"] ||= nil
-          %w[context recommendation].each { |key| text!(data[key], key) }
-          text!(data["rationale"], "rationale") if data.key?("rationale")
-          %w[options prerequisites].each do |key|
-            unless data[key].is_a?(Array) && data[key].length <= 8 && (key != "options" || !data[key].empty?)
-              raise Lifecycle::StateError, "proposal #{key} must be a bounded list"
-            end
-            data[key].each { |item| text!(item, key) }
-          end
-          if JSON.generate(data).bytesize > 3500 || Contract::SecretGate::PATTERN.match?(JSON.generate(data))
-            raise Lifecycle::StateError, "proposal must be bounded and non-secret"
-          end
-          data
-        end
-
-        def text!(value, field)
-          unless value.is_a?(String) && value.valid_encoding? && !value.strip.empty? &&
-              value.bytesize <= 1024 && !value.include?("\0")
-            raise Lifecycle::StateError, "invalid proposal #{field}"
-          end
-        end
-
-        def timestamp(value)
-          time = Time.iso8601(value.to_s)
-          raise Lifecycle::StateError, "proposal time must be canonical UTC" unless time.utc.iso8601 == value
-          time
-        rescue ArgumentError
-          raise Lifecycle::StateError, "invalid proposal timestamp"
-        end
-
-        def acknowledge(record, delivered_at)
-          timestamp(delivered_at)
-          return record if record["delivered_at"] == delivered_at
-          unless record["state"] == "awaiting-delivery" && !record["delivered_at"]
-            raise Lifecycle::StateError, "proposal delivery acknowledgement changed"
-          end
-          record.merge("state" => "awaiting-decision", "delivered_at" => delivered_at,
-            "deadline" => (timestamp(delivered_at) + WINDOW).iso8601)
-        end
-
-        def reply(record, answer:, received_at:, sequence:, claimed:, applied: nil)
-          timestamp(received_at)
-          raise Lifecycle::StateError, "proposal reply has no admitted ingress" unless sequence.is_a?(Integer) && sequence.positive?
-          digest = Digest::SHA256.hexdigest(JSON.generate([sequence, received_at, answer]))
-          applied ||= record if record["reply_sequence"] == sequence
-          if applied
-            raise Lifecycle::StateError, "duplicate ingress sequence changed content" unless applied["reply_digest"] == digest
-            return record
-          end
-          return record if %w[superseded denied].include?(record["state"])
-          raise Lifecycle::StateError, "proposal has no acknowledged delivery" unless record["delivered_at"]
-          text!(answer, "answer")
-          Lifecycle::Kinds.check_answer!("proposal", answer)
-          verb, rationale = answer.strip.split(/\s+/, 2)
-          decision = {"approve" => "approved-explicitly", "veto" => "denied", "clarify" => "superseded"}[verb.downcase]
-          # Scope changes and all unrecognized replies stop automatic approval.
-          decision ||= "superseded"
-          if claimed
-            decision = record["state"]
-          elsif APPROVED.include?(record["state"]) && verb.downcase == "approve"
-            decision = record["state"]
-          end
-          result = record.merge("state" => decision, "last_sequence" => [record.fetch("last_sequence", 0), sequence].max,
-            "reply_sequence" => sequence, "reply_digest" => digest,
-            "captain_answer" => answer, "received_at" => received_at)
-          result.delete("captain_rationale")
-          result["captain_rationale"] = rationale if rationale && !rationale.strip.empty?
-          result["stop_requested"] = true if claimed && verb.downcase != "approve"
-          result["resolution"] = claimed ? "effect-already-claimed; stop remaining safely stoppable work" : decision
-          result
-        end
-
-        def resolve(record, checkpoint:, now:)
-          return record unless record["state"] == "awaiting-decision"
-          return record unless record["silence_delegated"] == true
-          return record if timestamp(now) < timestamp(record.fetch("deadline"))
-          valid = checkpoint["schema"] == "ace.hitl.hermes.ingress-checkpoint/v1" &&
-            checkpoint["project"].is_a?(String) && checkpoint["project"] == record["project_id"] &&
-            checkpoint["request"] == record["request_id"] && checkpoint["revision"] == record["revision_id"] &&
-            checkpoint["healthy"] == true && checkpoint["drained"] == true &&
-            checkpoint.dig("checkpoint", "through") == record["deadline"] &&
-            checkpoint.dig("checkpoint", "sequence").is_a?(Integer) &&
-            checkpoint.dig("checkpoint", "sequence") >= record.fetch("last_sequence", 0)
-          return record unless valid
-          record.merge("state" => "approved-by-silence", "resolution" => "approved-by-silence",
-            "resolved_at" => now, "ingress_checkpoint" => checkpoint["checkpoint"])
-        end
-      end
-    end
-  end
-end

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

@@ -1,126 +0,0 @@
-# frozen_string_literal: true
-
-require "ace/assign/organisms/attempt_coordinator"
-require_relative "../../lifecycle/binding"
-
-module Ace
-  module Hitl
-    module Providers
-      class Lab
-        # The managed binding policy (spec 8wq.t.34i): requests bind to
-        # the exact ACTIVE MANAGED attempt of the requesting actor,
-        # verified by the authoritative ace-assign coordinator under the
-        # assignment exclusion. with_active HOLDS that exclusion across
-        # the caller's locked transition, so an attempt that ends
-        # concurrently cancels the request instead of handing it fresh
-        # authority. Every doubt maps to the classified BindingError —
-        # unknown identity/authority is an error, never permission.
-        class AssignmentBinding < Lifecycle::Binding
-          def initialize(coordinator: nil, repo_root: nil, project: nil, owner_guard: nil)
-            unless (project.nil? && owner_guard.nil?) ||
-                (project.is_a?(String) && !project.empty? && owner_guard.respond_to?(:call))
-              raise ArgumentError, "installed binding needs both a fixed project and its owner guard"
-            end
-            @coordinator = coordinator
-            @repo_root = repo_root
-            @project, @owner_guard = project, owner_guard
-          end
-
-          def validate_request(assignment:, attempt:, project:, requester:, caller_pid: nil)
-            with_verified(assignment, attempt, project, requester) do
-              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(assignment:, attempt:, project:, caller_pid:)
-            verify_selection!(project)
-            unless caller_pid.is_a?(Integer) && caller_pid.positive?
-              raise Lifecycle::BindingError, "kernel requester process identity is unavailable"
-            end
-            binding = coordinator.runtime_binding(attempt_id: attempt, caller_pid: caller_pid)
-            {"schema" => Ref::SCHEMA, "session" => binding.fetch("session"), "pane" => binding.fetch("pane")}
-          rescue Ace::Assign::Error => e
-            raise Lifecycle::BindingError, "native requester authority is unavailable (#{e.message})"
-          end
-
-          # The liveness scope: the assignment exclusion is HELD across
-          # the yielded transition commit.
-          def with_active(assignment:, attempt:, project: nil, requester: nil)
-            with_verified(assignment, attempt, project, requester) { yield }
-          end
-
-          def proposal_journal(project:)
-            unless project.is_a?(String) && !project.empty?
-              raise Lifecycle::BindingError, "proposal requires an explicit project"
-            end
-            verify_selection!(project)
-            coordinator.send(:journal_for)
-          end
-
-          def proposal_projects
-            if @project
-              verify_selection!(@project)
-              return [@project]
-            end
-            coordinator.send(:journal_for).proposals.map { |record| record.fetch("project_id") }.uniq.sort
-          end
-
-          private
-
-          def verify_selection!(project)
-            return unless @project
-            raise Lifecycle::BindingError, "project differs from installed HITL owner" unless project == @project
-            @owner_guard.call
-          end
-
-          def with_verified(assignment_id, attempt_id, project_id, requester)
-            # ONLY the authority verification is error-mapped: the
-            # caller's transition (answer hand-off, commits, effects)
-            # keeps its own failure classes — mapping it into
-            # BindingError would cancel a live request on an unrelated
-            # failure (review 8x327bud). The exclusion still spans the
-            # whole transition, so the phase flag separates the two.
-            verifying = true
-            verify_selection!(project_id)
-            coordinator.with_verified_attempt(
-              assignment_id: assignment_id,
-              attempt_id: attempt_id,
-              project_id: project_id,
-              requester: requester
-            ) do |attempt|
-              verify_selection!(project_id)
-              verifying = false
-              yield attempt
-            end
-          rescue Ace::Assign::Error => e
-            raise verifying ? map_error(e) : e
-          end
-
-          def coordinator
-            @coordinator ||= Ace::Assign::Organisms::AttemptCoordinator.new(repo_root: @repo_root)
-          end
-
-          def map_error(error)
-            message = error.message.to_s
-            case error.class.name
-            when /NotFound/
-              # An unknown attempt id is a verifiably dead binding.
-              Lifecycle::EndedAttemptError.new("HITL attempt is unknown: #{message}")
-            when /ReceiptRejected/
-              Lifecycle::EndedAttemptError.new(message)
-            when /UnauthorizedIdentity/
-              # A foreign actor on the record means the attempt moved on.
-              Lifecycle::EndedAttemptError.new("HITL requester does not own the attempt: #{message}")
-            when /InvalidState/
-              Lifecycle::EndedAttemptError.new(message)
-            else
-              Lifecycle::BindingError.new(message)
-            end
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-require "etc"
-require_relative "../../lifecycle/binding"
-
-module Ace
-  module Hitl
-    module Providers
-      class Lab
-        # The deployed shared service uses the original protected launch owner;
-        # standalone ordinary HITL continues to select its explicit coordinator.
-        class ProtectedAssignmentBinding < Lifecycle::Binding
-          def initialize(authority:, kernel:, journals:)
-            @authority, @kernel = authority, kernel
-            @journals = journals.dup.freeze
-          end
-
-          def validate_request(assignment:, attempt:, project:, requester:, caller_pid: nil)
-            peer = actual_peer!(caller_pid)
-            unless Etc.getpwuid(peer.fetch("uid")).name == requester
-              raise Lifecycle::BindingError, "HITL requester differs from kernel principal"
-            end
-            selected(assignment, attempt, project, peer.fetch("uid"), peer) { |reverse| reverse }
-          end
-
-          def reverse_address(assignment:, attempt:, project:, caller_pid:)
-            peer = actual_peer!(caller_pid)
-            selected(assignment, attempt, project, peer.fetch("uid"), peer) { |reverse| reverse }
-          end
-
-          def with_active(assignment:, attempt:, project:, requester:)
-            uid = Etc.getpwnam(requester).uid
-            selected(assignment, attempt, project, uid, nil) { yield }
-          rescue ArgumentError
-            raise Lifecycle::BindingError, "HITL requester is unavailable"
-          end
-
-          def proposal_journal(project:)
-            @journals.fetch(project)
-          rescue KeyError
-            raise Lifecycle::BindingError, "HITL project journal is not installed"
-          end
-
-          def proposal_projects
-            @journals.keys.sort.freeze
-          end
-
-          private
-
-          def actual_peer!(pid)
-            unless pid.is_a?(Integer) && pid.positive?
-              raise Lifecycle::BindingError, "HITL kernel requester is unavailable"
-            end
-            peer = @kernel.capture(pid)
-            @kernel.live!(peer)
-            peer
-          end
-
-          def selected(assignment, attempt, project, uid, peer, &block)
-            proposal_journal(project: project)
-            verifying = true
-            @authority.with_worker_hitl!(assignment: assignment, attempt: attempt,
-              project: project, requester_uid: uid, peer: peer) do |reverse|
-              verifying = false
-              block.call(reverse)
-            end
-          rescue Ace::Assign::AttemptErrors::InvalidState, Ace::Assign::AttemptErrors::NotFound => error
-            raise verifying ? Lifecycle::EndedAttemptError.new(error.message) : error
-          rescue Ace::Assign::Error, Ace::Runtime::RuntimeUnavailableError => error
-            raise verifying ? Lifecycle::BindingError.new("protected HITL owner unavailable (#{error.class.name})") : error
-          end
-        end
-      end
-    end
-  end
-end

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

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-require "ace/hitl/contract"
-require_relative "lab"
-
-module Ace
-  module Hitl
-    # HITL provider adapters (spec 8wm.t.vrz): pluggable ask/delivery
-    # transports behind one interface. Agent-facing ace-hitl paths resolve
-    # adapters through this registry only — never a concrete transport.
-    module Providers
-      REGISTRY = {
-        Lab::PROVIDER_NAME => -> { Lab.new }
-      }.freeze
-
-      module_function
-
-      def available
-        REGISTRY.keys.sort
-      end
-
-      def resolve(name)
-        factory = REGISTRY[name.to_s]
-        unless factory
-          raise UnknownProviderError,
-            "unknown HITL provider '#{name}' (available: #{available.join(', ')})"
-        end
-
-        factory.call
-      end
-    end
-  end
-end