ace-hitl 0.9.0 → 0.11.0

data/lib/ace/hitl/cli/commands/duty.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # The standing-duty projection: pending + escalated (spec
+        # 8wm.t.y21 §7).
+        class Duty < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Project pending and escalated HITL requests (transport operation)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(Lifecycle::Duty.project(pending: lifecycle_client.pending, states: lifecycle_client.states))
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/lifecycle_command.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Shared plumbing for the lifecycle commands (spec 8wm.t.y21 §8,
+        # scoped by 8wq.t.34i): every lifecycle operation reaches the
+        # store through the AUTHENTICATED BOUNDARY CLIENT — direct
+        # shared-store access is not a CLI option — and machine outputs
+        # are one JSON line, byte-compatible with the migrated CLI
+        # contract.
+        module LifecycleCommand
+          STDIN_READER = ->(limit) { $stdin.read(limit) }.freeze
+
+          def lifecycle_client
+            Providers::Lab.boundary_client
+          end
+
+          def overseer
+            channel_root = ENV.fetch("ACE_HITL_OVERSEER_CHANNEL_ROOT", "/lab/state/overseer-channel")
+            Lifecycle::Overseer.new(outbox_dir: File.join(channel_root, "outbox"))
+          end
+
+          def emit(result)
+            puts JSON.generate(result)
+          end
+
+          def raise_lifecycle_error(message)
+            raise Ace::Support::Cli::Error.new(message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/overseer_ack.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Host-broker acknowledgement of one relayed Overseer response.
+        class OverseerAck < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Acknowledge (remove) one relayed Overseer response"
+
+          argument :id, required: true, desc: "Overseer response message id"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(id:, **options)
+            emit(overseer.ack(id))
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/overseer_pending.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Host-broker drain view of the Overseer response outbox.
+        class OverseerPending < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "List queued Overseer responses (host-broker operation)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(overseer.pending)
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/overseer_send.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # The Root Overseer's bounded, type-tagged response through the
+        # reverse address (spec 8wm.t.y21 §6). The response is read from
+        # stdin.
+        class OverseerSend < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "Queue a bounded, type-tagged Overseer response (stdin)"
+
+          option :"reply-to", type: :string, desc: "Source message id this response answers"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(overseer.send_response(
+              reply_to: options[:"reply-to"] || "",
+              reader: LifecycleCommand::STDIN_READER
+            ))
+          rescue Lifecycle::Error => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/pending.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Host-broker listing of answerable relay requests; never purges
+        # or cancels anything (W651).
+        class Pending < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "List answerable HITL relay requests (transport operation)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(lifecycle_client.pending)
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/serve.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "../../lifecycle"
+require_relative "../../providers/providers"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # The installed scoped store boundary (spec 8wq.t.34i): serves
+        # the private HITL store over a peer-authenticated UNIX socket.
+        # Authorization facts come only from the trusted grants
+        # document; the store root and socket paths come from the
+        # deployment (options/environment), never from caller payloads.
+        class Serve < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Run the authenticated HITL store boundary service (peer-credential access)"
+
+          option :socket, type: :string, desc: "Boundary socket path (default: ACE_HITL_SOCKET or /run/lab/hitl.sock)"
+          option :store_root, type: :string, desc: "Private store root (default: ACE_HITL_STORE_ROOT or /run/lab/hitl)"
+          option :grants_path, type: :string, desc: "Trusted grants document (default: ACE_HITL_GRANTS_PATH or /etc/lab/ace-lab/authorization.yml)"
+          option :repo_root, type: :string, desc: "Candidate repository for the managed attempt authority"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+          option :verbose, type: :boolean, aliases: %w[-v], desc: "Show verbose output"
+
+          def call(**options)
+            policy = Providers::Lab.grants_policy(grants_path: grants_path(options))
+            unless policy.service_uid
+              raise_cli_error(
+                "the HITL service requires trusted grants with hitl.service_uid " \
+                "(#{grants_path(options)}); serving without a trusted service identity would " \
+                "fail every client endpoint verification"
+              )
+            end
+            binding_policy = Providers::Lab::CompositeBinding.new(
+              assignment: Providers::Lab.assignment_binding(repo_root: options[:repo_root]),
+              work: Providers::Lab::DaemonBinding.new
+            )
+            service = Lifecycle::Service.new(
+              root: store_root(options),
+              binding: binding_policy,
+              policy: policy,
+              socket_path: socket_path(options),
+              logger: options[:verbose] ? ->(message) { warn message } : nil
+            )
+            service.run
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_cli_error(e.message)
+          end
+
+          private
+
+          def socket_path(options)
+            options[:socket] || ENV[Providers::Lab::SOCKET_PATH_ENV] || Providers::Lab::DEFAULT_SOCKET_PATH
+          end
+
+          def store_root(options)
+            options[:store_root] || ENV[Providers::Lab::STORE_ROOT_ENV] || Providers::Lab::DEFAULT_STORE_ROOT
+          end
+
+          def grants_path(options)
+            options[:grants_path] || ENV[Providers::Lab::GRANTS_PATH_ENV] || Providers::Lab::DEFAULT_GRANTS_PATH
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/states.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require_relative "lifecycle_command"
+
+module Ace
+  module Hitl
+    module CLI
+      module Commands
+        # Host-broker listing of all public lifecycle projections.
+        class States < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include LifecycleCommand
+
+          desc "List public HITL lifecycle projections (transport operation)"
+
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            emit(lifecycle_client.states)
+          rescue Lifecycle::Error, Providers::ProviderUnavailableError => e
+            raise_lifecycle_error(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/cli/commands/wait.rb

@@ -55,11 +55,11 @@ module Ace
               lab_request_id = event.metadata["lab_request_id"]
               puts "Lab request delivered: #{event.id} (#{result[:lab_state]})"
               puts "Lab request: #{lab_request_id}"
-              puts "Consume the answer when ready: lab-hitl consume #{lab_request_id}"
+              puts "Consume the answer when ready from the lab relay."
               if result[:lab_state] == "callback-ok"
                 puts "Effect callback: ok"
               elsif result[:lab_state] == "callback-escalated"
-                puts "Effect callback: escalated; inspect with: lab-hitl duty"
+                puts "Effect callback: escalated; inspect the lab duty projection"
               end
             when :timeout
               raise Ace::Support::Cli::Error.new("Timed out waiting for HITL event '#{ref}'")

data/lib/ace/hitl/cli.rb

@@ -8,6 +8,16 @@ require_relative "cli/commands/show"
 require_relative "cli/commands/list"
 require_relative "cli/commands/update"
 require_relative "cli/commands/wait"
+require_relative "cli/commands/deliver"
+require_relative "cli/commands/consume"
+require_relative "cli/commands/cancel"
+require_relative "cli/commands/pending"
+require_relative "cli/commands/states"
+require_relative "cli/commands/duty"
+require_relative "cli/commands/serve"
+require_relative "cli/commands/overseer_send"
+require_relative "cli/commands/overseer_pending"
+require_relative "cli/commands/overseer_ack"
 
 module Ace
   module Hitl
@@ -22,7 +32,16 @@ module Ace
         ["show", "Show HITL event details"],
         ["list", "List HITL events"],
         ["update", "Update HITL event metadata or answer"],
-        ["wait", "Wait for an answer on a specific HITL event"]
+        ["wait", "Wait for an answer on a specific HITL event"],
+        ["deliver", "Deliver an answer (stdin) to a pending HITL relay request"],
+        ["consume", "Wait for and consume the answer of one own HITL relay request"],
+        ["cancel", "Cancel one HITL relay request with an audited reason"],
+        ["pending", "List answerable HITL relay requests (transport)"],
+        ["states", "List public HITL lifecycle projections (transport)"],
+        ["duty", "Project pending and escalated HITL requests (transport)"],
+        ["overseer-send", "Queue a bounded, type-tagged Overseer response (stdin)"],
+        ["overseer-pending", "List queued Overseer responses (host-broker)"],
+        ["overseer-ack", "Acknowledge one relayed Overseer response"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -40,6 +59,16 @@ module Ace
       register "list", CLI::Commands::List
       register "update", CLI::Commands::Update
       register "wait", CLI::Commands::Wait
+      register "deliver", CLI::Commands::Deliver
+      register "consume", CLI::Commands::Consume
+      register "cancel", CLI::Commands::Cancel
+      register "pending", CLI::Commands::Pending
+      register "states", CLI::Commands::States
+      register "duty", CLI::Commands::Duty
+      register "serve", CLI::Commands::Serve
+      register "overseer-send", CLI::Commands::OverseerSend
+      register "overseer-pending", CLI::Commands::OverseerPending
+      register "overseer-ack", CLI::Commands::OverseerAck
 
       version_cmd = Ace::Support::Cli::VersionCommand.build(
         gem_name: "ace-hitl",

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "securerandom"
+
+module Ace
+  module Hitl
+    module Lifecycle
+      # Durable, permission-preserving JSON record writes (port of
+      # atomic_json): O_EXCL|O_NOFOLLOW tempfile in the target directory,
+      # fsync, chmod, chown, rename. Ownership transitions go through the
+      # injectable ownership strategy; production performs real chown(2),
+      # tests map names onto the current identity (spec 8wm.t.y21 §2).
+      module AtomicJson
+        Ownership = Struct.new(:uid, :gid)
+
+        DEFAULT_OWNERSHIP = Object.new.tap do |strategy|
+          strategy.define_singleton_method(:chown) do |path, ownership|
+            File.chown(ownership.uid, ownership.gid, path) if ownership
+          end
+        end.freeze
+
+        module_function
+
+        # mode is an Integer permission bits value; ownership nil keeps
+        # the current identity. exclusive commits with link(2) instead of
+        # rename(2), so an existing destination raises Errno::EEXIST
+        # instead of being silently replaced (create-once writes).
+        def call(path, value, mode:, ownership: nil, ownership_strategy: DEFAULT_OWNERSHIP,
+          exclusive: false)
+          path = Pathname.new(path)
+          path.parent.mkpath
+          # The random suffix makes the temporary unique per invocation:
+          # a fixed pid-based name lets a competing writer's cleanup
+          # delete our in-flight temporary and fail both writes (review
+          # 8wq2zttt on PR#336). Cleanup only ever touches this call's
+          # own file.
+          temporary = path.parent.join(".#{path.basename}.tmp.#{$PROCESS_ID}.#{SecureRandom.hex(4)}")
+          flags = File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW
+          fd = IO.sysopen(temporary, flags, mode)
+          begin
+            io = IO.for_fd(fd, mode: "w")
+            begin
+              io.write(JSON.generate(value))
+              io.write("\n")
+              io.flush
+              io.fsync
+            ensure
+              io.close
+            end
+          rescue
+            begin
+              temporary.unlink
+            rescue
+              nil
+            end
+            raise
+          end
+          File.chmod(mode, temporary)
+          ownership_strategy.chown(temporary, ownership)
+          if exclusive
+            File.link(temporary, path)
+          else
+            File.rename(temporary, path)
+          end
+        ensure
+          temporary.unlink if temporary&.exist?
+        end
+
+        def read(path)
+          JSON.parse(File.read(path))
+        rescue SystemCallError, JSON::ParserError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Lifecycle
+      # The binding seam between the generic request lifecycle and the
+      # domain that owns Work/Attempt liveness and attribution (spec
+      # 8wm.t.y21 §1). The store REQUIRES a binding; the generic core
+      # never carries Work/Attempt semantics itself.
+      #
+      # Implementations must fail closed: any doubt raises BindingError.
+      class Binding
+        # Validate a request creation against the requester's exact live
+        # attempt. Raises BindingError on any violation or unavailability.
+        def validate_request(work: nil, assignment: nil, attempt:, project:, requester:)
+          raise NotImplementedError
+        end
+
+        # Re-verify that the attempt is still live before an answer is
+        # delivered or consumed. Raises BindingError when terminal.
+        def require_active(work:, attempt:)
+          raise NotImplementedError
+        end
+
+        # Hold verified live authority across ONE whole transition: the
+        # check and the caller's locked commit happen inside the same
+        # exclusion, so a concurrent attempt termination cannot land
+        # between them (spec 8wq.t.34i). The yielded value is opaque.
+        # Implementations without a holdable exclusion verify and yield
+        # (the legacy gap); the assignment authority holds its lock.
+        def with_active(work: nil, assignment: nil, attempt:, project: nil, requester: nil)
+          require_active(work: work, attempt: attempt)
+          yield
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "socket"
+require_relative "protocol"
+
+module Ace
+  module Hitl
+    module Lifecycle
+      # The authenticated client of the scoped store boundary (spec
+      # 8wq.t.34i). The CLI lifecycle operations run through this client;
+      # direct shared-store access is not a client-side option.
+      #
+      # Both endpoint directions are authenticated:
+      # - the client authenticates the SERVICE: the socket must be a
+      #   socket owned by the configured service uid, not group/world
+      #   writable, and the connected peer must BE the service uid;
+      # - the service authenticates the client from kernel peer
+      #   credentials (server side).
+      #
+      # Transport failures raise classified Lifecycle::TransportError;
+      # classified lifecycle errors arrive from the service and are
+      # re-raised under their own classes.
+      class Client
+        attr_reader :socket_path, :service_uid
+
+        def initialize(socket_path:, service_uid:, deadline_seconds: Protocol::DEFAULT_DEADLINE_SECONDS)
+          @socket_path = socket_path.to_s
+          @service_uid = Integer(service_uid)
+          @deadline_seconds = deadline_seconds
+        end
+
+        # @return [Hash] the result frame
+        def request(op, params = {})
+          verify_endpoint!
+          socket = UNIXSocket.open(@socket_path)
+          begin
+            verify_service_peer!(socket)
+            socket.write(Protocol.encode_request(op, params))
+            socket.flush
+            line = read_line(socket, deadline_for(op, params))
+            Protocol.decode_response(line)
+          ensure
+            socket.close
+          end
+        rescue SystemCallError, IOError, EOFError => e
+          raise TransportError, "HITL boundary is unavailable (#{e.class}: #{e.message})"
+        rescue JSON::GeneratorError => e
+          raise TransportError, "HITL boundary request is not serializable (#{e.message})"
+        end
+
+        def create(**params)
+          request("create", params.transform_keys(&:to_s))
+        end
+
+        def read(id)
+          request("read", {"id" => id})
+        end
+
+        def deliver(id, answer)
+          request("deliver", {"id" => id, "answer" => answer.to_s})
+        end
+
+        def consume(id, timeout: 0, operation: nil)
+          params = {"id" => id, "timeout" => Integer(timeout)}
+          params["operation"] = operation if operation
+          request("consume", params)
+        end
+
+        def cancel(id, reason: "")
+          request("cancel", {"id" => id, "reason" => reason.to_s})
+        end
+
+        def pending
+          request("pending")
+        end
+
+        def states
+          request("states")
+        end
+
+        def ping
+          request("ping")
+        end
+
+        private
+
+        # The endpoint must be owned by the trusted service identity and
+        # safe to write: an attacker-owned or world-writable socket is a
+        # credential-disclosure channel (answers, OTP) and is refused
+        # before any byte is sent.
+        def verify_endpoint!
+          stat = File.lstat(@socket_path)
+          unless stat.socket?
+            raise TransportError, "HITL boundary endpoint is not a socket: #{@socket_path}"
+          end
+          if stat.uid != @service_uid
+            raise TransportError,
+              "HITL boundary endpoint is owned by uid #{stat.uid}, not the trusted service uid #{@service_uid}"
+          end
+          # The designed endpoint mode is 0660 service:control-group —
+          # group-write is the legitimate access path; WORLD-write is
+          # never acceptable (no chmod-to-world workaround, spec 8wq.t.34i).
+          if (stat.mode & 0o002) != 0
+            raise TransportError, "HITL boundary endpoint is world-writable"
+          end
+        rescue Errno::ENOENT
+          raise TransportError, "HITL boundary endpoint does not exist: #{@socket_path}"
+        rescue SystemCallError
+          raise TransportError, "HITL boundary endpoint is not verifiable: #{@socket_path}"
+        end
+
+        def verify_service_peer!(socket)
+          peer_uid, = peer_credentials(socket)
+          return if peer_uid == @service_uid
+
+          raise TransportError,
+            "HITL boundary peer is uid #{peer_uid}, not the trusted service uid #{@service_uid}"
+        end
+
+        def peer_credentials(socket)
+          socket.getpeereid
+        end
+
+        # A consume without a timeout waits indefinitely at the client
+        # boundary too; every bounded call gets a deadline slightly
+        # beyond its own wait so the server result wins the race.
+        def deadline_for(op, params)
+          if op == "consume" && Integer(params["timeout"]) <= 0
+            nil
+          else
+            Process.clock_gettime(Process::CLOCK_MONOTONIC) + @deadline_seconds + Integer(params["timeout"])
+          end
+        rescue ArgumentError, TypeError
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) + @deadline_seconds
+        end
+
+        def read_line(socket, deadline)
+          data = +""
+          loop do
+            remaining = deadline && deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            raise TransportError, "HITL boundary deadline exceeded" if remaining && remaining <= 0
+            ready = IO.select([socket], nil, nil, remaining)
+            raise TransportError, "HITL boundary deadline exceeded" unless ready
+
+            chunk = socket.read_nonblock(4096, exception: false)
+            raise TransportError, "HITL boundary closed before responding" if chunk.nil?
+            # A spurious not-ready result goes back to select; only the
+            # deadline ends the wait (review 8x32r9b4).
+            next if chunk == :wait_readable
+
+            data << chunk
+            if data.bytesize > Protocol::MAX_FRAME_BYTES
+              raise TransportError, "HITL boundary response is too large"
+            end
+            return data if data.include?("\n")
+          end
+        end
+      end
+    end
+  end
+end