ace-runtime 0.1.1 → 0.3.0

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

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require_relative "protected_artifact_set"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Immutable local installer input. This contains selections only; live
+      # process and resource observations must come from their owning readers.
+      class ReadinessConfiguration
+        LIMIT = 65_536
+        SCHEMA = "ace.assign.readiness/v1"
+        FIELDS = %w[authority boundary_manifest mapping_id native project_id runtime schema slot_id worker].freeze
+        attr_reader :data
+
+        def self.path(slot)
+          unless slot.is_a?(String) && slot.match?(/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/)
+            raise RuntimeUnavailableError, "invalid readiness slot"
+          end
+          "/etc/ace/execution-slots/#{slot}/readiness.json"
+        end
+
+        def self.decode(bytes, slot:)
+          text = bytes.dup.force_encoding(Encoding::UTF_8)
+          unless text.bytesize.between?(1, LIMIT) && text.valid_encoding?
+            raise RuntimeUnavailableError, "readiness configuration is not bounded UTF-8"
+          end
+          new(JSON.parse(text, create_additions: false, max_nesting: 8,
+            allow_duplicate_key: false, allow_comments: false), slot: slot)
+        rescue JSON::ParserError, EncodingError
+          raise RuntimeUnavailableError, "readiness configuration is not strict JSON"
+        end
+
+        def self.load(slot:)
+          ProtectedArtifactSet.new.with do |artifacts|
+            bytes, = artifacts.read_path!(path(slot), limit: LIMIT)
+            value = decode(bytes, slot: slot)
+            artifacts.verify_unchanged!
+            value
+          end
+        end
+
+        def initialize(data, slot:)
+          object!(data, FIELDS)
+          unless data["schema"] == SCHEMA && data["slot_id"] == slot
+            refuse!("readiness configuration selection differs")
+          end
+          %w[mapping_id project_id].each do |key|
+            refuse!("invalid readiness identifier") unless data[key].is_a?(String) &&
+              data[key].match?(/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/)
+          end
+          object!(data.fetch("authority"), %w[gid groups socket_path uid])
+          object!(data.fetch("worker"), %w[gid groups uid])
+          %w[authority worker].each do |kind|
+            principal = data.fetch(kind)
+            unless %w[uid gid].all? { |key| principal[key].is_a?(Integer) && principal[key].positive? } &&
+                principal["groups"].is_a?(Array) && principal["groups"].all? { |gid| gid.is_a?(Integer) && gid.positive? } &&
+                principal["groups"].sort.uniq == principal["groups"]
+              refuse!("readiness principal differs")
+            end
+          end
+          native = data.fetch("native")
+          object!(native, %w[executable executable_sha256 protocol socket_path version workspace_id])
+          unless native["protocol"] == 22 && native["version"] == "0.9.3" &&
+              native["workspace_id"].is_a?(String) && native["workspace_id"].match?(/\Aw[1-9][0-9]{0,8}\z/)
+            refuse!("readiness native protocol differs")
+          end
+          digest!(native["executable_sha256"])
+          boundary = data.fetch("boundary_manifest")
+          object!(boundary, %w[path sha256])
+          unless boundary["path"] == "/etc/ace/execution-slots/#{slot}/boundary-manifest.json"
+            refuse!("readiness boundary path differs")
+          end
+          digest!(boundary["sha256"])
+          [data.dig("authority", "socket_path"), native["socket_path"], native["executable"]].each { |path| path!(path) }
+          runtime = data.fetch("runtime")
+          object!(runtime, %w[dependencies interpreter_path load_paths])
+          path!(runtime.fetch("interpreter_path"))
+          paths = runtime.fetch("load_paths")
+          unless paths.is_a?(Array) && paths.size.between?(1, 16) && paths.uniq == paths
+            refuse!("readiness load paths differ")
+          end
+          paths.each { |path| path!(path) }
+          dependencies = runtime.fetch("dependencies")
+          unless dependencies.is_a?(Array) && dependencies.size.between?(1, 256) &&
+              dependencies.map { |ref| ref.fetch("path") }.uniq.size == dependencies.size
+            refuse!("readiness dependency closure differs")
+          end
+          dependencies.each do |ref|
+            object!(ref, %w[bytes path sha256])
+            path!(ref.fetch("path"))
+            digest!(ref.fetch("sha256"))
+            unless ref["bytes"].is_a?(Integer) && ref["bytes"].between?(1, ProtectedArtifactSet::LIMIT)
+              refuse!("readiness dependency size differs")
+            end
+          end
+          @data = immutable(data)
+          freeze
+        rescue KeyError, TypeError, ArgumentError
+          refuse!("readiness configuration fields differ")
+        end
+
+        def verify_selection!(mapping_id:, mapping:, authority:, installation:)
+          expected = {"schema" => SCHEMA, "slot_id" => mapping.fetch("execution_scope").fetch("slot_id"),
+            "mapping_id" => mapping_id, "project_id" => mapping.fetch("project_id"),
+            "authority" => authority.slice("socket_path", "uid", "gid", "groups"),
+            "worker" => {"uid" => mapping.fetch("worker_uid"), "gid" => mapping.fetch("worker_gid"),
+              "groups" => mapping.fetch("worker_groups")}, "native" => mapping.fetch("native"),
+            "boundary_manifest" => {"path" => "/etc/ace/execution-slots/#{data.fetch('slot_id')}/boundary-manifest.json",
+              "sha256" => mapping.fetch("execution_scope").fetch("boundary_manifest_sha256")}, "runtime" => data.fetch("runtime")}
+          refuse!("readiness configuration does not join protected deployment") unless data == expected
+          artifacts = installation.fetch("artifacts")
+          closure = data.fetch("runtime").fetch("dependencies")
+          unless closure.all? { |ref| artifacts.any? { |artifact|
+              %w[runtime_dependency readiness_executable].include?(artifact.fetch("role")) &&
+                artifact.fetch("view_path") == ref.fetch("path") && artifact.fetch("sha256") == ref.fetch("sha256") } } &&
+              artifacts.any? { |artifact| artifact.fetch("role") == "runtime_dependency" &&
+                artifact.fetch("view_path") == data.dig("runtime", "interpreter_path") }
+            refuse!("readiness dependency closure does not join installation")
+          end
+          true
+        end
+
+        private
+
+        def object!(value, keys)
+          refuse!("readiness object fields differ") unless value.is_a?(Hash) && value.keys.sort == keys.sort
+        end
+
+        def path!(value)
+          refuse!("readiness path differs") unless value.is_a?(String) && value.bytesize.between?(2, 4096) &&
+            value.start_with?("/") && !value.include?("\0") && File.expand_path(value) == value
+        end
+
+        def digest!(value)
+          refuse!("readiness digest differs") unless value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+        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
+          end
+        end
+
+        def refuse!(message) = raise(RuntimeUnavailableError, message)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+require_relative "protected_artifact_set"
+require "rbconfig"
+
+module Ace
+  module Runtime
+    module Molecules
+      # The private hook installs this guard before loading its ACE dependencies.
+      # Every executable file is verified before require can evaluate it.
+      class ReadinessRuntime
+        BUILTINS = %w[enumerator.so thread.rb fiber.so rational.so complex.so ruby2_keywords.rb].freeze
+
+        def initialize(configuration:, artifacts: ProtectedArtifactSet.new)
+          @runtime, @artifacts = configuration.fetch("runtime"), artifacts
+          @references = @runtime.fetch("dependencies").to_h { |ref| [ref.fetch("path"), ref] }.freeze
+        end
+
+        def activate!(features: $LOADED_FEATURES, load_paths: $LOAD_PATH)
+          verify_loaded!(features)
+          @runtime.fetch("load_paths").each do |path|
+            ProtectedSocket.root_path!(path, directory: true)
+          end
+          load_paths.replace(@runtime.fetch("load_paths"))
+          @initialized_builtins ||= BUILTINS.select { |feature| features.include?(feature) }.freeze
+          owner = self
+          guard = Module.new do
+            define_method(:require) do |feature|
+              return false if owner.builtin_loaded?(feature)
+              path = owner.resolve!(feature)
+              owner.verify_file!(path)
+              super(path)
+            end
+            define_method(:require_relative) do |feature|
+              caller_file = caller_locations(1, 1).first.absolute_path
+              path = owner.resolve!(File.expand_path(feature, File.dirname(caller_file)))
+              owner.verify_file!(path)
+              require(path)
+            end
+            private :require, :require_relative
+          end
+          Kernel.prepend(guard)
+          true
+        end
+
+        def verify_loaded!(features)
+          features.each do |feature|
+            next if BUILTINS.include?(feature)
+            unless feature.is_a?(String) && feature.start_with?("/") && @references.key?(feature)
+              raise RuntimeUnavailableError, "readiness startup loaded undeclared code"
+            end
+            verify_file!(feature)
+          end
+          true
+        end
+
+        def builtin_loaded?(feature)
+          return false unless feature.is_a?(String) && @initialized_builtins
+          @initialized_builtins.any? do |builtin|
+            feature == builtin || feature == builtin.sub(/\.(?:rb|so)\z/, "")
+          end
+        end
+
+        def resolve!(feature)
+          unless feature.is_a?(String) && !feature.include?("\0")
+            raise RuntimeUnavailableError, "readiness require selection differs"
+          end
+          bases = feature.start_with?("/") ? [feature] : @runtime.fetch("load_paths").map { |path| File.join(path, feature) }
+          extension = "." + RbConfig::CONFIG.fetch("DLEXT")
+          candidates = bases.flat_map do |path|
+            # Ruby maps explicit .so/.o requests to its own platform extension.
+            if path.end_with?(".so", ".o")
+              [path.sub(/\.(?:so|o)\z/, extension)]
+            elsif path.end_with?(".rb", extension)
+              [path]
+            else
+              [path, path + ".rb", path + extension]
+            end
+          end
+          selected = candidates.find { |path| @references.key?(path) }
+          raise RuntimeUnavailableError, "readiness require is outside protected closure" unless selected
+          selected
+        end
+
+        def verify_file!(path)
+          @artifacts.with do |reader|
+            reader.read!(@references.fetch(path))
+            reader.verify_unchanged!
+          end
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "rbconfig"
+require_relative "linux_mount_info"
+require_relative "../errors"
+
+module Ace
+  module Runtime
+    module Molecules
+      # Observes declared reachable objects in a pinned server root. This does
+      # not enter or modify a namespace and carries no admission authority.
+      class ServerResourceObservation
+        VIEW_PATHS = %w[/proc /proc/sys /sys /sys/fs/cgroup /dev /dev/pts /dev/mqueue /dev/shm /tmp /var/tmp].freeze
+        MOUNT_FIELDS = %w[mount_id parent_id major_minor root mountpoint options filesystem_type].freeze
+        class Files
+          OPENAT2 = 437
+          RESOLVE = 0x10 | 0x04 # IN_ROOT | NO_SYMLINKS; bind mounts are allowed.
+
+          def supported!
+            unless RUBY_PLATFORM.include?("linux") && %w[x86_64 aarch64 arm64].include?(RbConfig::CONFIG.fetch("host_cpu"))
+              raise RuntimeUnavailableError, "contained server-root observation is unsupported"
+            end
+          end
+
+          def namespace(pid, kind = "mnt")
+            File.open("/proc/#{pid}/ns/#{kind}", File::RDONLY) { |file| identity(file.stat) }
+          end
+
+          def observe(pid, entries, authority_socket:)
+            supported!
+            root = File.open("/proc/#{pid}/root", File::RDONLY)
+            namespace = File.open("/proc/#{pid}/ns/mnt", File::RDONLY)
+            network = File.open("/proc/#{pid}/ns/net", File::RDONLY)
+            network_identity = network_identity!(network)
+            ipc = File.open("/proc/#{pid}/ns/ipc", File::RDONLY)
+            hook_ipc = File.open("/proc/self/ns/ipc", File::RDONLY)
+            root_identity, namespace_identity = identity(root.stat), identity(namespace.stat)
+            ipc_identity, hook_ipc_identity = identity(ipc.stat), identity(hook_ipc.stat)
+            table = LinuxMountInfo.new(File.read("/proc/#{pid}/mountinfo", LinuxMountInfo::LIMIT + 1))
+            raise RuntimeUnavailableError, "server mount inventory exceeds bound" if table.records.size > 256
+            topology = []
+            result = entries.map do |entry|
+              handle = open_inside(root, entry.fetch("view_path"))
+              begin
+                stat = handle.stat
+                raise RuntimeUnavailableError, "declared server resource is not a directory" unless stat.directory?
+                rows = File.read("/proc/self/fdinfo/#{handle.fileno}", 16_385).lines.filter_map do |line|
+                  /\Amnt_id:\s+([0-9]+)\s*\z/.match(line)&.[](1)
+                end
+                raise RuntimeUnavailableError, "server resource mount is ambiguous" unless rows.size == 1
+                mount = table.by_id(Integer(rows.first, 10))
+                topology << entry.slice("host_path", "view_path").merge(mount.slice("mountpoint", "root", "major_minor", "options"))
+                entry.slice("host_path", "view_path").merge("device" => stat.dev, "inode" => stat.ino,
+                  "uid" => stat.uid, "gid" => stat.gid, "filesystem_type" => mount.fetch("filesystem_type"),
+                  "mount_id" => mount.fetch("mount_id"))
+              ensure
+                handle.close
+              end
+            end
+            views = VIEW_PATHS.map { |path| pinned_view(root, path, table: table) }
+            socket_identity = pinned_socket(root, authority_socket)
+            ptmx_identity, ptmx_link = pinned_ptmx(root, table: table)
+            repeated = LinuxMountInfo.new(File.read("/proc/#{pid}/mountinfo", LinuxMountInfo::LIMIT + 1))
+            unless namespace_identity == self.namespace(pid) && root_identity == identity(File.stat("/proc/#{pid}/root")) &&
+                network_identity == self.namespace(pid, "net") &&
+                ipc_identity == self.namespace(pid, "ipc") && hook_ipc_identity == self.namespace("self", "ipc") &&
+                table.records == repeated.records &&
+                views == VIEW_PATHS.map { |path| pinned_view(root, path, table: repeated) } &&
+                socket_identity == pinned_socket(root, authority_socket) &&
+                [ptmx_identity, ptmx_link] == pinned_ptmx(root, table: repeated)
+              raise RuntimeUnavailableError, "server root or namespace changed during observation"
+            end
+            {"mount_namespace_identity" => namespace_identity, "network_namespace_identity" => network_identity, "resource_identities" => result, "resource_topology" => topology,
+              "kernel_view_topology" => {"ipc_namespace_identity" => ipc_identity, "hook_ipc_namespace_identity" => hook_ipc_identity,
+                "mounts" => table.records.map { |row| row.slice(*MOUNT_FIELDS) }, "views" => views, "authority_socket_identity" => socket_identity,
+                "ptmx_identity" => ptmx_identity, "ptmx_link" => ptmx_link}}
+          ensure
+            root&.close
+            namespace&.close
+            network&.close
+            ipc&.close
+            hook_ipc&.close
+          end
+
+          private
+
+          # NS_GET_NSTYPE is an nsfs ioctl. Pin the original server's object,
+          # require CLONE_NEWNET, and retain it across the repeated path read.
+          def network_identity!(handle)
+            unless handle.ioctl(0xb703) == 0x40000000
+              raise RuntimeUnavailableError, "server object is not a network namespace"
+            end
+            identity(handle.stat)
+          rescue SystemCallError, IOError
+            raise RuntimeUnavailableError, "server network namespace type is unavailable"
+          end
+
+          def identity(stat) = {"device" => stat.dev, "inode" => stat.ino}
+
+          def pinned_view(root, path, table:)
+            handle = open_inside(root, path, flags: 0x200000 | File::NOFOLLOW) # O_PATH, no data access.
+            stat = handle.stat
+            raise RuntimeUnavailableError, "fixed server view is not a directory" unless stat.directory?
+            rows = File.read("/proc/self/fdinfo/#{handle.fileno}", 16_385).lines.filter_map { |line| /\Amnt_id:\s+([0-9]+)\s*\z/.match(line)&.[](1) }
+            raise RuntimeUnavailableError, "fixed view mount is ambiguous" unless rows.size == 1
+            mount = table.by_id(Integer(rows.first, 10))
+            {"path" => path, "mount_id" => mount.fetch("mount_id"), "device" => stat.dev, "inode" => stat.ino, "type" => "directory"}
+          ensure
+            handle&.close
+          end
+
+          def pinned_socket(root, path)
+            handle = open_inside(root, path, flags: 0x200000 | File::NOFOLLOW)
+            stat = handle.stat
+            raise RuntimeUnavailableError, "authority projection is not a socket" unless stat.socket?
+            [stat.dev, stat.ino, stat.uid]
+          ensure
+            handle&.close
+          end
+
+          def pinned_ptmx(root, table:)
+            dev = open_inside(root, "/dev", flags: 0x200000 | File::NOFOLLOW)
+            link = read_ptmx_link(dev)
+            raise RuntimeUnavailableError, "selected ptmx link differs" unless link == "pts/ptmx"
+            node = open_inside(root, "/dev/pts/ptmx", flags: 0x200000 | File::NOFOLLOW)
+            stat = node.stat
+            raise RuntimeUnavailableError, "selected ptmx is not a character device" unless stat.chardev? && stat.rdev_major == 5 && stat.rdev_minor == 2
+            rows = File.read("/proc/self/fdinfo/#{node.fileno}", 16_385).lines.filter_map { |line| /\Amnt_id:\s+([0-9]+)\s*\z/.match(line)&.[](1) }
+            raise RuntimeUnavailableError, "selected ptmx mount is ambiguous" unless rows.size == 1
+            mount = table.by_id(Integer(rows.first, 10))
+            [{"device" => stat.dev, "inode" => stat.ino, "mount_id" => mount.fetch("mount_id"), "type" => "character",
+              "rdev_major" => stat.rdev_major, "rdev_minor" => stat.rdev_minor}, link]
+          ensure
+            dev&.close
+            node&.close
+          end
+
+          def read_ptmx_link(dev)
+            call = Fiddle::Function.new(Fiddle::Handle::DEFAULT["readlinkat"],
+              [Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T], Fiddle::TYPE_SSIZE_T)
+            buffer = Fiddle::Pointer.malloc(64)
+            count = call.call(dev.fileno, "ptmx\0", buffer, 64)
+            raise RuntimeUnavailableError, "selected ptmx link cannot be observed" unless count.between?(1, 63)
+            buffer.to_s(count)
+          end
+
+          def open_inside(root, path, flags: File::RDONLY | File::NONBLOCK | File::NOFOLLOW)
+            unless path.is_a?(String) && path.bytesize.between?(1, 4096) && path.start_with?("/") &&
+                !path.include?("\0") && File.expand_path(path) == path
+              raise RuntimeUnavailableError, "server resource path differs"
+            end
+            syscall = Fiddle::Function.new(Fiddle::Handle::DEFAULT["syscall"],
+              [Fiddle::TYPE_LONG, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T],
+              Fiddle::TYPE_LONG)
+            how = [flags, 0, RESOLVE].pack("Q<Q<Q<")
+            descriptor = syscall.call(OPENAT2, root.fileno, path + "\0", how, how.bytesize)
+            raise RuntimeUnavailableError, "contained server resource cannot be opened" if descriptor.negative?
+            IO.for_fd(descriptor, autoclose: true)
+          end
+        end
+
+        def initialize(kernel:, files: Files.new)
+          @kernel, @files = kernel, files
+        end
+
+        def observe!(server:, entries:, authority_socket:)
+          @kernel.live!(server)
+          before = @kernel.capture(server.fetch("pid"))
+          unless @kernel.same?(before, server)
+            raise RuntimeUnavailableError, "server incarnation differs"
+          end
+          result = @files.observe(server.fetch("pid"), entries, authority_socket: authority_socket)
+          @kernel.live!(server)
+          unless @kernel.same?(@kernel.capture(server.fetch("pid")), before)
+            raise RuntimeUnavailableError, "server credentials changed during resource observation"
+          end
+          result
+        end
+      end
+    end
+  end
+end