ace-runtime 0.2.0 → 0.4.0

data/lib/ace/runtime/molecules/kernel_view_topology.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+require_relative "server_resource_observation"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Pure verification of the fixed supported unit's live report. Installed
+      # profile verification and original host proof authentication are separate.
+      class KernelViewTopology
+        VIEWS = ServerResourceObservation::VIEW_PATHS
+        MOUNT_FIELDS = ServerResourceObservation::MOUNT_FIELDS.sort.freeze
+        READONLY = %w[/proc/sys /sys /sys/fs/cgroup /dev /dev/shm].freeze
+        APIS = {"/proc" => "proc", "/dev/pts" => "devpts", "/dev/mqueue" => "mqueue"}.freeze
+
+        def verify!(topology:, host_ipc:, authority_socket:, writable_resources:, host_devpts:, selected_devpts:)
+          object!(topology, %w[authority_socket_identity hook_ipc_namespace_identity ipc_namespace_identity mounts ptmx_identity ptmx_link views])
+          ipc = topology.fetch("ipc_namespace_identity")
+          namespace!(ipc)
+          namespace!(topology.fetch("hook_ipc_namespace_identity"))
+          namespace!(host_ipc)
+          refuse! unless ipc == topology.fetch("hook_ipc_namespace_identity") && ipc != host_ipc
+          socket = topology.fetch("authority_socket_identity")
+          refuse! unless socket.is_a?(Array) && socket.size == 3 && socket.all? { |n| n.is_a?(Integer) && n >= 0 } &&
+            socket.first(2).all?(&:positive?) && socket == authority_socket
+          mounts = topology.fetch("mounts")
+          refuse! unless mounts.is_a?(Array) && mounts.size.between?(1, 256)
+          mounts.each { |mount| mount!(mount) }
+          refuse! unless mounts.map { |row| row.fetch("mount_id") }.uniq.size == mounts.size
+          roots = mounts.select { |row| row.fetch("mountpoint") == "/" }
+          refuse! unless !roots.empty? && roots.all? { |row| readonly?(row) }
+          views = topology.fetch("views")
+          refuse! unless views.is_a?(Array) && views.size == VIEWS.size && views.map { |view| view.fetch("path") }.sort == VIEWS.sort
+          by_path = views.to_h do |view|
+            object!(view, %w[device inode mount_id path type])
+            refuse! unless view["type"] == "directory" && %w[device inode mount_id].all? { |key| positive?(view[key]) }
+            row = mounts.find { |mount| mount.fetch("mount_id") == view.fetch("mount_id") }
+            refuse! unless row && covers?(row.fetch("mountpoint"), view.fetch("path"))
+            [view.fetch("path"), row]
+          end
+          READONLY.each { |path| refuse! unless readonly?(by_path.fetch(path)) }
+          APIS.each do |path, filesystem|
+            row = by_path.fetch(path)
+            refuse! unless row.fetch("mountpoint") == path && row.fetch("root") == "/" && row.fetch("filesystem_type") == filesystem
+          end
+          object!(host_devpts, %w[device inode major_minor])
+          object!(selected_devpts, %w[device inode major_minor path ptmx_inode])
+          [host_devpts, selected_devpts].each do |instance|
+            refuse! unless %w[device inode].all? { |key| positive?(instance[key]) } &&
+              instance["major_minor"].is_a?(String) && instance["major_minor"].match?(/\A(?:0|[1-9][0-9]*):(?:0|[1-9][0-9]*)\z/)
+          end
+          refuse! unless positive?(selected_devpts["ptmx_inode"]) && path?(selected_devpts["path"])
+          pts = views.find { |view| view["path"] == "/dev/pts" }
+          pts_mount = by_path.fetch("/dev/pts")
+          refuse! unless pts.values_at("device", "inode") == selected_devpts.values_at("device", "inode") &&
+            pts_mount["major_minor"] == selected_devpts["major_minor"] &&
+            selected_devpts["device"] != host_devpts["device"] && selected_devpts["major_minor"] != host_devpts["major_minor"] &&
+            topology["ptmx_link"] == "pts/ptmx"
+          ptmx = topology.fetch("ptmx_identity")
+          object!(ptmx, %w[device inode mount_id rdev_major rdev_minor type])
+          refuse! unless ptmx["type"] == "character" && %w[device inode mount_id].all? { |key| positive?(ptmx[key]) } &&
+            ptmx["rdev_major"].is_a?(Integer) && ptmx["rdev_minor"].is_a?(Integer) &&
+            ptmx.values_at("rdev_major", "rdev_minor") == [5, 2] &&
+            ptmx.values_at("device", "inode") == selected_devpts.values_at("device", "ptmx_inode")
+          node_mount = mounts.find { |row| row["mount_id"] == ptmx["mount_id"] }
+          refuse! unless node_mount && readonly?(node_mount) &&
+            node_mount.values_at("mountpoint", "root", "filesystem_type", "major_minor") ==
+              ["/dev/pts/ptmx", "/ptmx", "devpts", selected_devpts["major_minor"]]
+          hidden_host = mounts.select { |row| row["major_minor"] == host_devpts["major_minor"] }
+          hidden_host.each do |row|
+            refuse! unless row.values_at("mountpoint", "root", "filesystem_type") == ["/dev/pts", "/", "devpts"]
+          end
+          refuse! unless hidden_host.size <= 1
+          pts_layers = mounts.select { |row| row["mountpoint"] == "/dev/pts" }
+          refuse! unless (pts_layers - [pts_mount] - hidden_host).empty?
+          unless hidden_host.empty?
+            chain = []
+            parent = pts_mount
+            while parent["mountpoint"] == "/dev/pts"
+              refuse! if chain.include?(parent["mount_id"])
+              chain << parent.fetch("mount_id")
+              parent = mounts.find { |row| row["mount_id"] == parent["parent_id"] }
+              refuse! unless parent
+            end
+            refuse! unless hidden_host.all? { |row| chain.include?(row["mount_id"]) }
+          end
+          refuse! unless by_path.fetch("/dev").fetch("filesystem_type") == "tmpfs" && by_path.fetch("/dev").fetch("mountpoint") == "/dev"
+          mounts.each do |row|
+            next if hidden_host.include?(row)
+            next if readonly?(row)
+            api = APIS[row.fetch("mountpoint")]
+            next if api && row == by_path.fetch(row.fetch("mountpoint")) && row.fetch("filesystem_type") == api
+            refuse! if %w[/dev /proc /sys].any? { |root| covers?(root, row.fetch("mountpoint")) }
+            refuse! unless writable_resources.any? do |resource|
+              row.values_at("mountpoint", "major_minor", "root") == resource.values_at("view_path", "major_minor", "filesystem_path") &&
+                row.fetch("filesystem_type") == resource.fetch("filesystem_type")
+            end
+          end
+          %w[/tmp /var/tmp].each do |path|
+            row = by_path.fetch(path)
+            refuse! unless readonly?(row) || writable_resources.any? { |resource| resource["view_path"] == path && row["mountpoint"] == path }
+          end
+          true
+        rescue KeyError, TypeError, NoMethodError, ArgumentError
+          refuse!
+        end
+
+        private
+
+        def mount!(row)
+          object!(row, MOUNT_FIELDS)
+          refuse! unless positive?(row["mount_id"]) && row["parent_id"].is_a?(Integer) && row["parent_id"] >= 0 &&
+            row["major_minor"].is_a?(String) && row["major_minor"].match?(/\A[0-9]+:[0-9]+\z/) &&
+            path?(row["root"]) && path?(row["mountpoint"]) && row["filesystem_type"].is_a?(String) &&
+            row["filesystem_type"].match?(/\A[a-zA-Z0-9_.-]+\z/) && row["options"].is_a?(Array) &&
+            row["options"].all? { |option| option.is_a?(String) && option.bytesize.between?(1, 128) } &&
+            row["options"].uniq == row["options"] && (row["options"] & %w[ro rw]).size == 1
+        end
+        def object!(value, fields)
+          refuse! unless value.is_a?(Hash) && value.keys.sort == fields.sort
+        end
+        def namespace!(value)
+          object!(value, %w[device inode])
+          refuse! unless value.values.all? { |number| positive?(number) }
+        end
+        def positive?(number) = number.is_a?(Integer) && number.positive?
+        def path?(path) = path.is_a?(String) && path.bytesize.between?(1, 4096) && path.start_with?("/") && !path.include?("\0") && File.expand_path(path) == path
+        def covers?(root, path) = root == "/" || root == path || path.start_with?(root + "/")
+        def readonly?(row) = row.fetch("options").include?("ro")
+        def refuse! = raise(RuntimeUnavailableError, "live kernel/resource view does not match the supported profile")
+      end
+    end
+  end
+end

data/lib/ace/runtime/molecules/owned_child_scope.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+module Ace
+  module Runtime
+    module Molecules
+      # One ephemeral single-thread helper owns every child in this scope.
+      # Linux reparents detached orphans to this subreaper, not container PID1.
+      # Unreaped direct children pin their PIDs until this owner reaps them.
+      class OwnedChildScope
+        class CleanupUncertain < StandardError; end
+
+        def initialize
+          unless RUBY_PLATFORM.include?("linux") && Thread.list.count(&:alive?) == 1
+            raise CleanupUncertain, "child scope requires a sole Linux helper thread"
+          end
+          @owner = Process.pid
+          raise CleanupUncertain, "child scope has preexisting children" unless children.empty?
+          # An inherited ignore/custom reaper could discard a child's wait
+          # status and unpin its PID. This sole ephemeral helper owns the
+          # disposition; establish it while the verified child set is empty.
+          Signal.trap("CHLD", "DEFAULT")
+          prctl = Fiddle::Function.new(Fiddle::Handle::DEFAULT["prctl"],
+            [Fiddle::TYPE_INT, Fiddle::TYPE_LONG, Fiddle::TYPE_LONG, Fiddle::TYPE_LONG, Fiddle::TYPE_LONG], Fiddle::TYPE_INT)
+          raise CleanupUncertain, "cannot establish child subreaper" unless prctl.call(36, 1, 0, 0, 0).zero?
+        end
+
+        # Preserve the leader's wait status for the executor. Kill/reap only
+        # kernel-owned direct children; adoption closes setsid/double-fork escape.
+        def cleanup!(leader:, timeout: 5)
+          unless Process.pid == @owner && Thread.list.count(&:alive?) == 1 &&
+              timeout.is_a?(Numeric) && timeout.finite? && timeout.positive? && timeout <= 5
+            raise CleanupUncertain, "child scope ownership is unavailable"
+          end
+          deadline = monotonic + timeout
+          owned = children
+          raise CleanupUncertain, "original child is no longer owned" unless owned.include?(leader)
+          signal("TERM", -leader)
+          loop do
+            owned = children
+            raise CleanupUncertain, "original child was reaped outside its scope" unless owned.include?(leader)
+            owned.each do |pid|
+              signal("KILL", pid)
+              Process.waitpid(pid, Process::WNOHANG) unless pid == leader
+            end
+            remaining = children
+            return if remaining == [leader] && zombie?(leader)
+            raise CleanupUncertain, "owned child cleanup deadline elapsed" if monotonic >= deadline
+            IO.select(nil, nil, nil, 0.01)
+          end
+        rescue Errno::ECHILD, Errno::ENOENT, IOError
+          raise CleanupUncertain, "owned child cleanup cannot be confirmed"
+        end
+
+        private
+
+        def children
+          File.open("/proc/self/task/#{@owner}/children", "r") do |file|
+            bytes = file.read(65_537) || ""
+            raise CleanupUncertain, "owned child inventory exceeds bound" if bytes.bytesize > 65_536
+            values = bytes.split.map { |value| Integer(value, 10) }
+            unless values.uniq == values && values.all?(&:positive?)
+              raise CleanupUncertain, "owned child inventory is invalid"
+            end
+            values.sort
+          end
+        end
+
+        def signal(name, pid)
+          Process.kill(name, pid)
+        rescue Errno::ESRCH
+          nil
+        end
+
+        def zombie?(pid) = File.read("/proc/#{pid}/stat").rpartition(")").last.split.first == "Z"
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/ace/runtime/molecules/process_identity.rb

@@ -3,6 +3,7 @@
 require "open3"
 require "socket"
 require "fiddle"
+require "time"
 
 module Ace
   module Runtime
@@ -117,6 +118,33 @@ module Ace
             {"liveness" => "unknown", "observed_at" => at, "reason" => "process identity no longer observable"}
           end
         end
+
+        # Positive evidence that this exact historical generation ended. A
+        # failed capture alone says nothing: EPERM/inaccessible probes remain
+        # unknown. PID reuse is conclusive only when the exact birth differs.
+        def generation_status(identity, process: Process)
+          at = Time.now.utc.iso8601
+          unknown = {"liveness" => "unknown", "observed_at" => at}
+          unless identity.is_a?(Hash) && identity.keys.sort == %w[host pid started_at uid] &&
+              identity["host"] == @hostname && identity["pid"].is_a?(Integer) && identity["pid"].positive? &&
+              identity["uid"].is_a?(Integer) && identity["uid"] >= 0 &&
+              identity["started_at"].is_a?(String) && !identity["started_at"].empty?
+            return unknown.merge("reason" => "verified process generation unavailable")
+          end
+          current = capture(identity.fetch("pid"))
+          return {"liveness" => "live", "observed_at" => at, "identity" => current} if current == identity
+          if current && current.fetch("started_at") != identity.fetch("started_at")
+            return {"liveness" => "ended", "observed_at" => at, "reason" => "pid generation replaced", "identity" => current}
+          end
+          begin
+            process.kill(0, identity.fetch("pid"))
+            unknown.merge("reason" => "process address exists but generation is unobservable")
+          rescue Errno::ESRCH
+            {"liveness" => "ended", "observed_at" => at, "reason" => "kernel reports no process at address"}
+          rescue SystemCallError
+            unknown.merge("reason" => "kernel process presence is unavailable")
+          end
+        end
       end
     end
   end

data/lib/ace/runtime/molecules/protected_artifact_set.rb

@@ -48,8 +48,17 @@ module Ace
           def trusted_owner?(stat) = stat.uid.zero?
         end
 
-        def initialize(protection: Protection.new)
+        def initialize(protection: Protection.new, file_limit: LIMIT, total_limit: TOTAL_LIMIT, count_limit: COUNT_LIMIT)
+          unless file_limit.is_a?(Integer) && total_limit.is_a?(Integer) &&
+              file_limit.positive? && total_limit.positive? && file_limit <= total_limit
+            raise ArgumentError, "invalid protected artifact byte budgets"
+          end
+          unless count_limit.is_a?(Integer) && count_limit.positive?
+            raise ArgumentError, "invalid protected artifact count budget"
+          end
           @protection = protection
+          @file_limit, @total_limit = file_limit, total_limit
+          @count_limit = count_limit
         end
 
         def with
@@ -67,9 +76,9 @@ module Ace
             raise RuntimeUnavailableError, "network artifact references conflict" unless previous == reference
             return @contents.fetch(path)
           end
-          raise RuntimeUnavailableError, "network artifact graph is oversized" if @references.size >= COUNT_LIMIT
+          raise RuntimeUnavailableError, "network artifact graph is oversized" if @references.size >= @count_limit
           size = reference.fetch("bytes")
-          unless size.is_a?(Integer) && size.between?(1, LIMIT) && @total + size <= TOTAL_LIMIT
+          unless size.is_a?(Integer) && size.between?(1, @file_limit) && @total + size <= @total_limit
             raise RuntimeUnavailableError, "network artifact bytes exceed bounds"
           end
           @protection.root_path!(path)
@@ -89,11 +98,66 @@ module Ace
           bytes
         end
 
+        # Trusted process handoff inside the same bounded verification. The
+        # duplicate refers to the authenticated retained inode, never a reopened
+        # pathname, and is closed before this callback can outlive the set.
+        def with_readonly_handle!(reference)
+          unless @handles && @references
+            raise RuntimeUnavailableError, "protected handle requires an active verification"
+          end
+          read!(reference)
+          verify_unchanged!
+          duplicate = @handles.fetch(reference.fetch("path")).fetch(:handle).dup
+          duplicate.close_on_exec = true
+          duplicate.rewind
+          begin
+            yield duplicate
+          ensure
+            verify_unchanged!
+          end
+        ensure
+          duplicate&.close unless duplicate&.closed?
+        end
+
+        # Fixed installer entrypoints have no caller-supplied digest. Derive the
+        # reference from the same protected descriptor whose bytes are retained.
+        def read_path!(path, limit: @file_limit)
+          raise ArgumentError, "invalid artifact byte limit" unless limit.is_a?(Integer) && limit.between?(1, @file_limit)
+          raise ArgumentError, "invalid fixed artifact path" unless path.is_a?(String) &&
+            path.start_with?("/") && !path.include?("\0") && File.expand_path(path) == path
+          if @references.key?(path)
+            reference = @references.fetch(path)
+            raise RuntimeUnavailableError, "fixed artifact exceeds bounds" if reference.fetch("bytes") > limit
+            return [@contents.fetch(path), reference].freeze
+          end
+          @protection.root_path!(path)
+          ancestors(path).reverse_each { |ancestor| pin!(ancestor, directory: true) }
+          handle = pin!(path, directory: false)
+          size = handle.stat.size
+          unless size.between?(1, limit) && @references.size < @count_limit && @total + size <= @total_limit
+            raise RuntimeUnavailableError, "fixed artifact exceeds bounds"
+          end
+          bytes = handle.read(size + 1)
+          unless bytes.is_a?(String) && bytes.bytesize == size
+            raise RuntimeUnavailableError, "fixed artifact length changed"
+          end
+          reference = {"path" => path.dup.freeze, "sha256" => Digest::SHA256.hexdigest(bytes).freeze,
+            "bytes" => size}.freeze
+          if @references.key?(path)
+            raise RuntimeUnavailableError, "fixed artifact references conflict" unless @references.fetch(path) == reference
+          else
+            @references[path] = reference
+            @contents[path] = bytes.freeze
+            @total += size
+          end
+          [@contents.fetch(path), reference].freeze
+        end
+
         def verify_unchanged!
           @handles.each do |path, entry|
             handle = entry.fetch(:handle)
-            unless snapshot(handle.stat) == entry.fetch(:snapshot) &&
-                snapshot(File.lstat(path)) == entry.fetch(:snapshot)
+            unless snapshot(handle.stat, directory: entry.fetch(:directory)) == entry.fetch(:snapshot) &&
+                snapshot(File.lstat(path), directory: entry.fetch(:directory)) == entry.fetch(:snapshot)
               raise RuntimeUnavailableError, "network artifact changed during verification"
             end
             @protection.verify!(path, handle, directory: entry.fetch(:directory))
@@ -126,10 +190,10 @@ module Ace
           begin
             handle.close_on_exec = true
             @protection.verify!(path, handle, directory: directory)
-            unless snapshot(stat) == snapshot(handle.stat) && snapshot(File.lstat(path)) == snapshot(handle.stat)
+            unless snapshot(stat, directory: directory) == snapshot(handle.stat, directory: directory) && snapshot(File.lstat(path), directory: directory) == snapshot(handle.stat, directory: directory)
               raise RuntimeUnavailableError, "network artifact changed while opening"
             end
-            @handles[path] = {handle: handle, directory: directory, snapshot: snapshot(handle.stat)}
+            @handles[path] = {handle: handle, directory: directory, snapshot: snapshot(handle.stat, directory: directory)}
             handle
           rescue Exception
             handle.close
@@ -137,8 +201,9 @@ module Ace
           end
         end
 
-        def snapshot(stat)
-          [stat.dev, stat.ino, stat.uid, stat.gid, stat.mode, stat.size, stat.mtime, stat.ctime]
+        def snapshot(stat, directory:)
+          identity = [stat.dev, stat.ino, stat.uid, stat.gid, stat.mode]
+          directory ? identity : identity + [stat.size, stat.mtime, stat.ctime]
         end
       end
     end

data/lib/ace/runtime/molecules/protected_socket.rb

@@ -7,6 +7,22 @@ module Ace
     module Molecules
       module ProtectedSocket
         LIMIT = 65_536
+        # Fixed protocols that forbid descriptors use this for every control,
+        # binary-body and EOF read; rights never bypass a later framing check.
+        class Ingress
+          def initialize(socket) = @socket = socket
+          def to_io = @socket
+
+          def read_nonblock(length, exception: false)
+            result = @socket.recvmsg_nonblock(length, 0, 4096, scm_rights: true, exception: exception)
+            return result if result == :wait_readable
+            return nil if result.nil?
+            bytes, _, flags, *controls = result
+            controls.each { |control| control.unix_rights&.each(&:close) if control.cmsg_is?(Socket::SOL_SOCKET, Socket::SCM_RIGHTS) }
+            raise SecurityError, "protected ancillary input is forbidden" unless controls.empty? && (flags & Socket::MSG_CTRUNC).zero?
+            bytes.empty? ? nil : bytes
+          end
+        end
         module_function
 
         def root_path!(path, directory: false, owner: 0)
@@ -48,9 +64,12 @@ module Ace
           socket&.close unless socket&.closed?
         end
 
-        def socket_identity(path)
+        def socket_identity(path, mode: nil)
           stat = File.lstat(path)
           raise RuntimeUnavailableError, "protected endpoint is not a socket" unless stat.socket? && !stat.symlink?
+          if !mode.nil? && (!mode.is_a?(Integer) || !mode.between?(0, 0o7777) || (stat.mode & 0o7777) != mode)
+            raise RuntimeUnavailableError, "protected endpoint mode differs"
+          end
           [stat.dev, stat.ino, stat.uid]
         rescue SystemCallError
           raise RuntimeUnavailableError, "protected endpoint is unavailable"
@@ -69,7 +88,10 @@ module Ace
             raise RuntimeUnavailableError, "protected socket frame is oversized" if buffer.bytesize > limit
             break if chunk == "\n"
           end
-          value = JSON.parse(buffer)
+          buffer.force_encoding(Encoding::UTF_8)
+          raise RuntimeUnavailableError, "protected socket frame is malformed" unless buffer.valid_encoding?
+          value = JSON.parse(buffer, create_additions: false, max_nesting: 32,
+            allow_duplicate_key: false, allow_comments: false)
           with_size ? {data: value, bytesize: buffer.bytesize} : value
         rescue JSON::ParserError
           raise RuntimeUnavailableError, "protected socket frame is malformed"

data/lib/ace/runtime/molecules/protected_task_context_entry.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+require "json"
+require_relative "protected_artifact_set"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Ref-only installed discovery. Domain publication owns the projection;
+      # the selected child remains the original scope/admission authority.
+      class ProtectedTaskContextEntry
+        PATH = "/etc/ace/task-context-entry.json"
+        PRESENCE_PATHS = %w[/etc/ace/assignment-authorities.json /etc/ace/assignment-deployment-history.json /usr/local/lib/lab/herdr.installation.json].freeze
+        SCHEMA = "ace.protected-task-context-entry-selection/v1"
+        MANIFEST_SCHEMA = "lab.protected-command-entry/v1"
+        ROLE = "ace-assign-task-context"
+        METADATA_LIMIT = 65_536
+        FILE_LIMIT = 33_554_432
+        TOTAL_LIMIT = 268_435_456
+        COUNT_LIMIT = 4_096
+        Entry = Struct.new(:pin, :manifest, :body, :interpreter, keyword_init: true)
+
+        def initialize(artifacts_factory: -> { ProtectedArtifactSet.new(file_limit: FILE_LIMIT, total_limit: TOTAL_LIMIT, count_limit: COUNT_LIMIT) },
+          stat: File.method(:lstat))
+          @factory, @stat = artifacts_factory, stat
+        end
+
+        # Pure shape validation, never publication/original admission authority.
+        def validate_pin!(pin)
+          pin!(pin)
+        end
+
+        def with
+          unless present?(PATH)
+            refuse!("installed discovery is absent") if PRESENCE_PATHS.any? { |path| present?(path) }
+            return yield nil
+          end
+          @factory.call.with do |held|
+            @held = held
+            bytes, = held.read_path!(PATH, limit: METADATA_LIMIT)
+            projection = json!(bytes)
+            object!(projection, %w[schema task_context_entry])
+            refuse!("discovery schema") unless projection.fetch("schema") == SCHEMA
+            pin = pin!(projection.fetch("task_context_entry"))
+            held.verify_unchanged!
+            result = yield pin
+            held.verify_unchanged!
+            result
+          ensure
+            @held = nil
+          end
+        rescue KeyError, TypeError, NoMethodError, ArgumentError, IOError, SystemCallError, EncodingError
+          refuse!("installed discovery is unavailable")
+        end
+
+        # Live descriptor lifetime is this callback only. Exact protected bytes
+        # go to stdin; callers never execute/reopen a manifest-selected pathname.
+        def with_entry(pin)
+          refuse!("entry requires held discovery") unless @held
+          pin = pin!(pin)
+          manifest = json!(@held.read!(pin.fetch("manifest")))
+          object!(manifest, %w[schema role wrapper interpreter bootstrap])
+          unless manifest.fetch("schema") == MANIFEST_SCHEMA && manifest.fetch("role") == ROLE && manifest.fetch("wrapper") == pin.fetch("wrapper")
+            refuse!("selected fixed role differs")
+          end
+          reference!(manifest.fetch("interpreter"))
+          bootstrap = manifest.fetch("bootstrap")
+          object!(bootstrap, %w[original_source owner preparation startup_entries])
+          %w[original_source owner preparation].each do |key|
+            reference!(bootstrap.fetch(key))
+            @held.read!(bootstrap.fetch(key))
+          end
+          entries = bootstrap.fetch("startup_entries")
+          refuse!("bootstrap entry references") unless entries.is_a?(Hash)
+          reference!(entries.fetch("ace-assign"))
+          read_references!(entries)
+          body = @held.read!(pin.fetch("wrapper"))
+          text = body.dup.force_encoding(Encoding::UTF_8)
+          refuse!("wrapper source encoding") unless text.valid_encoding? && !text.include?("\0")
+          @held.with_readonly_handle!(manifest.fetch("interpreter")) do |interpreter|
+            stat = interpreter.stat
+            refuse!("selected interpreter is not executable") unless stat.file? && stat.executable? && (stat.mode & 0o6000).zero?
+            @held.verify_unchanged!
+            result = yield Entry.new(pin: pin, manifest: immutable(manifest), body: body, interpreter: interpreter).freeze
+            @held.verify_unchanged!
+            result
+          end
+        rescue KeyError, TypeError, NoMethodError, ArgumentError, IOError, SystemCallError, EncodingError
+          refuse!("selected protected entry is unavailable")
+        end
+
+        private
+
+        def present?(path)
+          @stat.call(path)
+          true
+        rescue Errno::ENOENT
+          false
+        end
+
+        def pin!(pin)
+          object!(pin, %w[manifest wrapper])
+          reference!(pin.fetch("manifest"), limit: METADATA_LIMIT)
+          reference!(pin.fetch("wrapper"))
+          immutable(pin)
+        end
+
+        def reference!(reference, limit: FILE_LIMIT)
+          object!(reference, %w[bytes path sha256])
+          path = reference.fetch("path")
+          unless path.is_a?(String) && path.encoding == Encoding::UTF_8 && path.valid_encoding? &&
+              path.bytesize.between?(2, 4096) && path.start_with?("/") && !path.include?("\0") && File.expand_path(path) == path &&
+              reference.fetch("bytes").is_a?(Integer) && reference.fetch("bytes").between?(1, limit) &&
+              reference.fetch("sha256").is_a?(String) && reference.fetch("sha256").match?(/\A[0-9a-f]{64}\z/)
+            refuse!("protected entry reference")
+          end
+        end
+
+        def read_references!(root)
+          pending = [root]
+          until pending.empty?
+            value = pending.pop
+            if value.is_a?(Hash) && value.keys.sort == %w[bytes path sha256]
+              reference!(value)
+              @held.read!(value)
+            elsif value.is_a?(Hash) && value.keys.all? { |key| key.is_a?(String) }
+              pending.concat(value.values)
+            elsif value.is_a?(Array)
+              pending.concat(value)
+            else
+              refuse!("bootstrap reference graph")
+            end
+          end
+        end
+
+        def json!(bytes)
+          text = bytes.dup.force_encoding(Encoding::UTF_8)
+          refuse!("entry metadata encoding or bound") unless text.valid_encoding? && text.bytesize.between?(1, METADATA_LIMIT)
+          JSON.parse(text, create_additions: false, max_nesting: 32, allow_duplicate_key: false, allow_comments: false)
+        rescue JSON::ParserError
+          refuse!("entry metadata JSON")
+        end
+
+        def object!(value, fields)
+          refuse!("entry fields") unless value.is_a?(Hash) && value.keys.sort == fields.sort
+        end
+
+        def immutable(value)
+          case value
+          when Hash then value.to_h { |key, item| [key.dup.freeze, immutable(item)] }.freeze
+          when Array then value.map { |item| immutable(item) }.freeze
+          when String then value.dup.freeze
+          else value.freeze
+          end
+        end
+
+        def refuse!(detail)
+          raise RuntimeUnavailableError, "protected task-context entry unavailable: #{detail}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/runtime/molecules/protected_worker_entry.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Ace
+  module Runtime
+    module Molecules
+      # Structural admission of source-owned pins. Artifact authentication belongs
+      # to the selected entry owner; these references are never an execution grant.
+      module ProtectedWorkerEntry
+        LIMITS = {"interpreter" => 33_554_432, "wrapper" => 1_048_576}.freeze
+
+        def self.validate!(value)
+          unless value.is_a?(Hash) && value.keys.sort == LIMITS.keys.sort
+            raise ArgumentError, "worker entry fields differ"
+          end
+          LIMITS.each do |key, limit|
+            reference = value[key]
+            unless reference.is_a?(Hash) && reference.keys.sort == %w[bytes path sha256] &&
+                reference["bytes"].is_a?(Integer) && reference["bytes"].between?(1, limit) &&
+                reference["sha256"].is_a?(String) && reference["sha256"].match?(/\A[0-9a-f]{64}\z/) &&
+                reference["path"].is_a?(String) && reference["path"].encoding == Encoding::UTF_8 &&
+                reference["path"].valid_encoding? && reference["path"].bytesize.between?(2, 4096) &&
+                !reference["path"].include?("\0") && reference["path"].start_with?("/") &&
+                File.expand_path(reference["path"]) == reference["path"]
+              raise ArgumentError, "worker entry reference differs"
+            end
+          end
+          value
+        end
+      end
+    end
+  end
+end