ace-assign 0.64.0 → 0.66.1

data/lib/ace/assign/authority/deployment.rb

@@ -6,9 +6,14 @@ require "rbconfig"
 require "openssl"
 require_relative "private_directory"
 require_relative "posix_acl"
+require_relative "task_context_entry"
+require_relative "campaign_consumer_policy"
+require "ace/runtime/molecules/protected_worker_entry"
 require "ace/runtime/molecules/protected_socket"
+require "ace/runtime/molecules/protected_artifact_set"
 require "ace/runtime/molecules/protected_linux"
 require "ace/runtime/molecules/execution_unit_installation"
+require "ace/runtime/molecules/readiness_configuration"
 
 module Ace
   module Assign
@@ -16,15 +21,48 @@ module Ace
       class Deployment
         PATH = "/etc/ace/assignment-authorities.json"
         TOKEN = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
-        attr_reader :data
+        attr_reader :data, :artifact_reference
 
         def self.load
-          wire = Ace::Runtime::Molecules::ProtectedSocket
-          wire.root_path!(PATH)
-          raise ArgumentError, "deployment map is oversized" if File.size(PATH) > 65_536
-          new(JSON.parse(File.read(PATH)))
+          Ace::Runtime::Molecules::ProtectedArtifactSet.new.with do |artifacts|
+            bytes, reference = artifacts.read_path!(PATH, limit: 65_536)
+            deployment = from_verified_bytes(bytes, reference)
+            artifacts.verify_unchanged!
+            deployment
+          end
+        end
+
+        # Trusted installer source call only; this is not a transport selector.
+        # Authentication establishes fixed descriptor bytes, not installed readiness.
+        def self.load_artifact(reference)
+          unless reference.is_a?(Hash) && reference.keys.sort == %w[bytes path sha256] &&
+              reference["path"].is_a?(String) && reference["path"].start_with?("/") &&
+              !reference["path"].include?("\0") && File.expand_path(reference["path"]) == reference["path"] &&
+              reference["sha256"].is_a?(String) && reference["sha256"].match?(/\A[0-9a-f]{64}\z/) &&
+              reference["bytes"].is_a?(Integer) && reference["bytes"].between?(1, 65_536)
+            raise ArgumentError, "invalid protected deployment artifact reference"
+          end
+          selected = reference.transform_values { |value| value.is_a?(String) ? value.dup.freeze : value }.freeze
+          Ace::Runtime::Molecules::ProtectedArtifactSet.new.with do |artifacts|
+            deployment = from_verified_bytes(artifacts.read!(selected), selected)
+            artifacts.verify_unchanged!
+            deployment
+          end
         end
 
+        def self.from_verified_bytes(raw, reference)
+          bytes = raw.dup.force_encoding(Encoding::UTF_8)
+          raise ArgumentError, "deployment artifact is not UTF-8" unless bytes.valid_encoding?
+          raise ArgumentError, "deployment artifact exceeds bounds" unless bytes.bytesize.between?(1, 65_536)
+          value = JSON.parse(bytes, create_additions: false, max_nesting: 32,
+            allow_duplicate_key: false, allow_comments: false)
+          deployment = new(value)
+          deployment.send(:freeze_data!, deployment.data)
+          deployment.instance_variable_set(:@artifact_reference, reference)
+          deployment.freeze
+        end
+        private_class_method :from_verified_bytes
+
         def initialize(data)
           unless data.is_a?(Hash) && data["schema"] == "ace.assign.authorities/v2" &&
               data.keys.sort == %w[authorities launch_mappings projects schema]
@@ -46,16 +84,18 @@ module Ace
           end
           @data["projects"].each_value do |project|
             raise ArgumentError, "invalid project mapping" unless project.is_a?(Hash)
-            keys = %w[journal_repository evidence_git_ref evidence_checkout_root assignment_root candidate_root
+            keys = %w[journal_repository evidence_git_ref evidence_checkout_root assignment_root candidate_root campaign_repository campaign_store_root campaign_policy
               launcher_uids reviewer_uids worker_uids service_executor_uids supervisor_uids peer_credentials]
             keys << "service_receivers" if project.key?("service_receivers")
             keys << "inbox_contexts" if project.key?("inbox_contexts")
             strict!(project, keys)
-            %w[journal_repository evidence_checkout_root assignment_root candidate_root].each { |key| path!(project.fetch(key)) }
+            CampaignConsumerPolicy.reference!(project.fetch("campaign_policy"))
+            %w[journal_repository evidence_checkout_root assignment_root candidate_root campaign_repository campaign_store_root].each { |key| path!(project.fetch(key)) }
             unless project["evidence_git_ref"] == "refs/ace/execution"
               raise ArgumentError, "protected authority uses the canonical execution ref"
             end
-            role_uids = %w[launcher_uids reviewer_uids worker_uids service_executor_uids supervisor_uids].flat_map do |key|
+            role_keys = %w[launcher_uids reviewer_uids worker_uids service_executor_uids supervisor_uids]
+            role_uids = role_keys.flat_map do |key|
               values = project.fetch(key)
               unless values.is_a?(Array) && values.all? { |id| id.is_a?(Integer) && id.positive? } && values == values.sort.uniq
                 raise ArgumentError, "invalid project principal allowlist"
@@ -105,10 +145,19 @@ module Ace
             raise ArgumentError, "receiver endpoint must be separate from private staging"
           end
           protected_roots = @data.fetch("authorities").values.map { |service| service.fetch("state_root") } +
-            @data.fetch("projects").values.flat_map { |project| %w[journal_repository evidence_checkout_root assignment_root candidate_root].map { |key| project.fetch(key) } }
+            @data.fetch("projects").values.flat_map { |project| %w[journal_repository evidence_checkout_root assignment_root candidate_root campaign_repository campaign_store_root].map { |key| project.fetch(key) } }
           if staging.any? { |root| protected_roots.any? { |protected| paths_overlap?(root, protected) } }
             raise ArgumentError, "receiver staging overlaps authority state"
           end
+          campaign_roots = @data.fetch("projects").values.flat_map { |project| project.values_at("campaign_repository", "campaign_store_root") }
+          other_roots = @data.fetch("authorities").values.map { |service| service.fetch("state_root") } +
+            @data.fetch("projects").values.flat_map { |project|
+              project.values_at("journal_repository", "evidence_checkout_root", "assignment_root", "candidate_root") +
+                project.fetch("peer_credentials").values.map { |peer| peer.fetch("scratch_root") } }
+          if campaign_roots.combination(2).any? { |left, right| paths_overlap?(left, right) } ||
+              campaign_roots.any? { |root| other_roots.any? { |other| paths_overlap?(root, other) } }
+            raise ArgumentError, "campaign roots overlap another protected or worker root"
+          end
           repositories = @data.fetch("projects").values.map { |project| project.fetch("journal_repository") }
           raise ArgumentError, "canonical project repository has duplicate mappings" unless repositories.uniq.size == repositories.size
           @data.fetch("projects").each_key do |project_id|
@@ -141,24 +190,13 @@ module Ace
           unless Process.uid == service.fetch("uid")
             raise Ace::Runtime::RuntimeUnavailableError, "inbox resolver must run as its installed authority"
           end
-          PrivateDirectory.verify!(context.fetch("deliveries_dir"))
-          verify_inbox_acl!(context.fetch("deliveries_dir"), private_leaf: true)
-          key_path = context.fetch("receipt_public_key")
-          client_path = context.fetch("pi_queue_client")
-          [key_path, client_path].each do |path|
-            Ace::Runtime::Molecules::ProtectedSocket.root_path!(path)
-            verify_inbox_acl!(path)
-            unless File.file?(path) && !File.symlink?(path) && File.readable?(path)
-              raise Ace::Runtime::RuntimeUnavailableError, "installed inbox artifact is unavailable"
-            end
-          end
-          unless File.executable?(client_path) && Digest::SHA256.file(client_path).hexdigest == context.fetch("pi_queue_client_sha256")
-            raise Ace::Runtime::RuntimeUnavailableError, "installed inbox identity client differs"
-          end
-          raise Ace::Runtime::RuntimeUnavailableError, "installed inbox public key is oversized" if File.size(key_path) > 16_384
-          key = OpenSSL::PKey.read(File.binread(key_path))
-          unless key.is_a?(OpenSSL::PKey::RSA) && !key.private?
-            raise Ace::Runtime::RuntimeUnavailableError, "installed inbox key must be public-only RSA"
+          credentials = context.fetch("owner_credentials")
+          path = context.fetch("control_socket_path")
+          wire = Ace::Runtime::Molecules::ProtectedSocket
+          wire.root_path!(File.dirname(path), directory: true, owner: credentials.fetch("uid"))
+          identity = wire.socket_identity(path)
+          unless identity.last == credentials.fetch("uid")
+            raise Ace::Runtime::RuntimeUnavailableError, "installed context owner endpoint differs"
           end
           context
         rescue AttemptErrors::ReceiptRejected, OpenSSL::PKey::PKeyError, SystemCallError
@@ -196,14 +234,22 @@ module Ace
 
         def validate_inbox_contexts!
           roots = []
+          service_scopes = data.fetch("launch_mappings").values.map { |map| map.fetch("execution_scope") }
+          service_owner_uids = []
           data.fetch("projects").each do |project_id, fixed_project|
             contexts = fixed_project.fetch("inbox_contexts", {})
             unless contexts.is_a?(Hash) && contexts.keys.all? { |id| id.is_a?(String) && TOKEN.match?(id) }
               raise ArgumentError, "invalid installed inbox context map"
             end
             contexts.each_value do |context|
-              strict!(context, %w[deliveries_dir receipt_public_key native_mapping_id pi_queue_client pi_queue_client_sha256 supervisor_uids])
-              %w[deliveries_dir receipt_public_key pi_queue_client].each { |key| path!(context.fetch(key)) }
+              fields = %w[control_socket_path deliveries_dir owner_credentials native_mapping_id pi_queue_client pi_queue_client_sha256 supervisor_uids]
+              fields << "service" if context.key?("service")
+              strict!(context, fields)
+              credentials = context.fetch("owner_credentials")
+              strict!(credentials, %w[gid groups uid])
+              principal!(credentials, "uid", "gid", "groups")
+              raise ArgumentError, "context owner group count exceeds bounds" if credentials.fetch("groups").size > 64
+              %w[control_socket_path deliveries_dir pi_queue_client].each { |key| path!(context.fetch(key)) }
               unless context["pi_queue_client_sha256"].is_a?(String) && context["pi_queue_client_sha256"].match?(/\A[0-9a-f]{64}\z/)
                 raise ArgumentError, "invalid installed Pi identity client digest"
               end
@@ -220,19 +266,48 @@ module Ace
               unless native.fetch("project_id") == project_id && authority(native.fetch("authority_id")).fetch("composition") == "services"
                 raise ArgumentError, "inbox context requires its services project mapping"
               end
+              if context.key?("service")
+                Ace::Runtime::Molecules::ExecutionUnitInstallation.validate_inbox_context_service!(context.fetch("service"))
+                scope = context.fetch("service").fetch("execution_scope")
+                if service_scopes.any? { |other|
+                  %w[slot_id slice_unit service_unit].any? { |field| scope.fetch(field) == other.fetch(field) } ||
+                    scope.values_at("root_directory", "runtime_directory").any? { |path|
+                      other.values_at("root_directory", "runtime_directory").any? { |existing| paths_overlap?(path, existing) }
+                    }
+                }
+                  raise ArgumentError, "context service shares a protected execution slot or backing root"
+                end
+                prohibited_uids = data.fetch("authorities").values.map { |service| service.fetch("uid") } +
+                  data.fetch("launch_mappings").values.flat_map { |map| map.values_at("launcher_uid", "worker_uid") } +
+                  data.fetch("projects").values.flat_map { |project|
+                    %w[launcher_uids reviewer_uids worker_uids service_executor_uids supervisor_uids].flat_map { |field| project.fetch(field) } +
+                      project.fetch("service_receivers", {}).values.map { |receiver| receiver.fetch("executor_uid") }
+                  }
+                prohibited_uids.concat(data.fetch("projects").values.flat_map { |project|
+                  project.fetch("inbox_contexts", {}).values.reject { |other| other.equal?(context) }.map { |other| other.fetch("owner_credentials").fetch("uid") }
+                })
+                uid = credentials.fetch("uid")
+                if prohibited_uids.include?(uid) || service_owner_uids.include?(uid)
+                  raise ArgumentError, "context service owner shares another protected principal"
+                end
+                service_owner_uids << uid
+                service_scopes << scope
+              end
               roots << context.fetch("deliveries_dir")
             end
           end
           forbidden = data.fetch("projects").values.flat_map do |fixed_project|
             fixed_project.fetch("peer_credentials").values.map { |peer| peer.fetch("scratch_root") } +
               fixed_project.fetch("service_receivers", {}).values.map { |receiver| receiver.fetch("staging_root") } +
-              %w[journal_repository evidence_checkout_root assignment_root candidate_root].map { |key| fixed_project.fetch(key) }
+              %w[journal_repository evidence_checkout_root assignment_root candidate_root campaign_repository campaign_store_root].map { |key| fixed_project.fetch(key) }
           end
           forbidden.concat(data.fetch("authorities").values.map { |service| service.fetch("state_root") })
           if roots.combination(2).any? { |left, right| paths_overlap?(left, right) } ||
               roots.any? { |root| forbidden.any? { |other| paths_overlap?(root, other) } }
             raise ArgumentError, "installed inbox private roots overlap protected state"
           end
+        rescue Ace::Runtime::RuntimeUnavailableError
+          raise ArgumentError, "invalid context service installation selection"
         end
         private :validate_inbox_contexts!
 
@@ -318,12 +393,43 @@ module Ace
           data.fetch("launch_mappings").fetch(id)
         end
 
+        # Canonical mapping identity shared by scope evidence and the trusted
+        # provisioning owner. Resolves only this descriptor's exact mapping ID.
+        def mapping_digest(id)
+          Digest::SHA256.hexdigest(JSON.generate(canonical_mapping_value(mapping(id)))).freeze
+        end
+
+        def canonical_mapping_value(value)
+          case value
+          when Hash then value.sort.to_h.transform_values { |item| canonical_mapping_value(item) }
+          when Array then value.map { |item| canonical_mapping_value(item) }
+          else value
+          end
+        end
+        private :canonical_mapping_value
+
         def validate_mapping!(id, mapping)
           required = %w[project_id authority_id launcher_uid launcher_gid launcher_groups worker_uid worker_gid
-            worker_groups worker_actor worker_cwd worker_argv worker_env bootstrap bootstrap_sha256 native execution_scope]
-          unless mapping.is_a?(Hash) && mapping.keys.sort == required.sort
+            worker_groups worker_actor worker_cwd worker_entry worker_env bootstrap bootstrap_sha256 native execution_scope task_context_entry]
+          workspace = %w[workspace_repository_id workspace_cleanup_config]
+          unless mapping.is_a?(Hash) && [required.sort, (required + workspace).sort].include?(mapping.keys.sort)
             raise ArgumentError, "launch mapping fields differ: #{id}"
           end
+          if mapping.key?("workspace_repository_id")
+            repository = mapping.fetch("workspace_repository_id")
+            unless repository.is_a?(String) && TOKEN.match?(repository)
+              raise ArgumentError, "workspace repository identity is invalid"
+            end
+            reference = mapping.fetch("workspace_cleanup_config")
+            strict!(reference, %w[path sha256 bytes])
+            path!(reference.fetch("path"))
+            unless reference.fetch("path").bytesize <= 4096 && reference.fetch("path").encoding == Encoding::UTF_8 && reference.fetch("path").valid_encoding? &&
+                digest?(reference.fetch("sha256")) && reference.fetch("bytes").is_a?(Integer) && reference.fetch("bytes").between?(1, 65_536)
+              raise ArgumentError, "workspace cleanup configuration reference is invalid"
+            end
+          end
+          TaskContextEntry.validate!(mapping.fetch("task_context_entry"))
+          Ace::Runtime::Molecules::ProtectedWorkerEntry.validate!(mapping.fetch("worker_entry"))
           service = authority(mapping.fetch("authority_id"))
           fixed_project = project(mapping.fetch("project_id"))
           %w[launcher worker].each do |role|
@@ -367,12 +473,10 @@ module Ace
               !paths_overlap?(scope.fetch("root_directory"), scope.fetch("runtime_directory"))
             raise ArgumentError, "execution scope backing roots overlap or runtime root is invalid"
           end
-          argv = mapping.fetch("worker_argv")
           env = mapping.fetch("worker_env")
-          unless argv.is_a?(Array) && !argv.empty? && argv.size <= 64 && argv.all? { |v| v.is_a?(String) && !v.include?("\0") } &&
-              argv.first.start_with?("/") && env.is_a?(Hash) && env.all? { |k, v| k.match?(/\A[A-Z_][A-Z0-9_]*\z/) && v.is_a?(String) && !v.include?("\0") } &&
+          unless env.is_a?(Hash) && env.all? { |k, v| k.match?(/\A[A-Z_][A-Z0-9_]*\z/) && v.is_a?(String) && !v.include?("\0") } &&
               env.keys.none? { |key| key.match?(/\A(?:LD_|DYLD_|RUBY|BUNDLE|PYTHON)/) }
-            raise ArgumentError, "invalid fixed worker argv or environment"
+            raise ArgumentError, "invalid fixed worker environment"
           end
           unless mapping["worker_actor"].is_a?(String) && !mapping["worker_actor"].empty? &&
               mapping["bootstrap_sha256"].match?(/\A[0-9a-f]{64}\z/)
@@ -402,6 +506,51 @@ module Ace
           end
         end
 
+        # Original ownership cannot be recycled or hidden by a staged descriptor.
+        def maintenance_inventory(candidate)
+          unless candidate.is_a?(Deployment) && artifact_reference && candidate.artifact_reference && frozen? && candidate.frozen?
+            raise AttemptErrors::EvidenceUnavailable, "maintenance requires authenticated immutable original and candidate descriptors"
+          end
+          originals = data.fetch("launch_mappings")
+          proposed = candidate.data.fetch("launch_mappings")
+          originals.each do |id, map|
+            next unless proposed.key?(id)
+            unless maintenance_association(map) == candidate.maintenance_association(proposed.fetch(id))
+              raise ArgumentError, "existing maintenance mapping was reassociated: #{id}"
+            end
+          end
+          entries = originals.map { |id, map| [id, self, map] } +
+            proposed.reject { |id, _| originals.key?(id) }.map { |id, map| [id, candidate, map] }
+          all = originals.map { |id, map| [id, self, map] } + proposed.map { |id, map| [id, candidate, map] }
+          all.combination(2).each do |left, right|
+            l_id, l_owner, l_map = left
+            r_id, r_owner, r_map = right
+            l_scope, r_scope = l_map.fetch("execution_scope"), r_map.fetch("execution_scope")
+            shared = %w[slot_id slice_unit service_unit network_namespace_path].any? { |key| l_scope.fetch(key) == r_scope.fetch(key) }
+            shared ||= l_scope.values_at("root_directory", "runtime_directory").product(
+              r_scope.values_at("root_directory", "runtime_directory")).any? { |a, b| paths_overlap?(a, b) }
+            if shared && (l_id != r_id || l_owner.maintenance_association(l_map) != r_owner.maintenance_association(r_map))
+              raise ArgumentError, "physical execution slot has conflicting maintenance ownership"
+            end
+          end
+          entries.sort_by(&:first).map { |entry| entry.freeze }.freeze
+        end
+
+        def maintenance_association(map)
+          fixed = project(map.fetch("project_id"))
+          [map.fetch("project_id"), fixed.values_at("journal_repository", "evidence_git_ref", "evidence_checkout_root"),
+            authority(map.fetch("authority_id")).fetch("state_root"),
+            map.fetch("execution_scope").values_at("slot_id", "slice_unit", "service_unit", "network_namespace_path")]
+        end
+
+        def freeze_data!(value)
+          case value
+          when Hash then value.each { |key, item| key.freeze; freeze_data!(item) }
+          when Array then value.each { |item| freeze_data!(item) }
+          end
+          value.freeze
+        end
+
         def strict!(value, keys)
           raise ArgumentError, "deployment fields differ" unless value.is_a?(Hash) && value.keys.sort == keys.sort
         end
@@ -438,11 +587,24 @@ module Ace
           manager ||= Ace::Runtime::Molecules::SystemdScopeManager.new(
             slice_unit: scope.fetch("slice_unit"), service_unit: scope.fetch("service_unit"))
           manifest = Ace::Runtime::Molecules::ExecutionUnitInstallation.new(scope: scope, native: map.fetch("native"),
-            bootstrap: map.fetch("bootstrap"), worker_executable: map.fetch("worker_argv").first,
+            bootstrap: map.fetch("bootstrap"), worker_entry: map.fetch("worker_entry"),
             worker_uid: map.fetch("worker_uid"), worker_gid: map.fetch("worker_gid")).verify!(manager: manager)
           artifacts = manifest.fetch("artifacts")
+          configuration = artifacts.find { |artifact| artifact.fetch("role") == "readiness_configuration" }
+          Ace::Runtime::Molecules::ProtectedArtifactSet.new.with do |reader|
+            bytes, = reader.read_path!(configuration.fetch("host_path"), limit: 65_536)
+            unless Digest::SHA256.hexdigest(bytes) == configuration.fetch("sha256")
+              raise Ace::Runtime::RuntimeUnavailableError, "readiness configuration content differs"
+            end
+            Ace::Runtime::Molecules::ReadinessConfiguration.decode(bytes, slot: scope.fetch("slot_id"))
+              .verify_selection!(mapping_id: id, mapping: map, authority: service, installation: manifest)
+            reader.verify_unchanged!
+          end
           bootstrap = artifacts.find { |artifact| artifact.fetch("role") == "bootstrap" }
-          executables = artifacts.select { |artifact| %w[bootstrap worker_executable].include?(artifact.fetch("role")) }
+          executables = artifacts.select do |artifact|
+            artifact.fetch("role") == "bootstrap" || (artifact.fetch("role") == "runtime_dependency" &&
+              artifact.fetch("view_path") == map.fetch("worker_entry").fetch("interpreter").fetch("path"))
+          end
           unless bootstrap.fetch("sha256") == map.fetch("bootstrap_sha256") && elf_architecture?(bootstrap.fetch("host_path")) &&
               executables.all? { |artifact| File.executable?(artifact.fetch("host_path")) }
             raise Ace::Runtime::RuntimeUnavailableError, "installed bootstrap or executable is unsafe"
@@ -450,7 +612,7 @@ module Ace
           wire.root_path!(File.dirname(service.fetch("socket_path")), directory: true, owner: service.fetch("uid"))
           if authority_state
             fixed = project(map.fetch("project_id"))
-            ([service.fetch("state_root")] + %w[journal_repository evidence_checkout_root assignment_root candidate_root].map { |key| fixed.fetch(key) }).each do |path|
+            ([service.fetch("state_root")] + %w[journal_repository evidence_checkout_root assignment_root candidate_root campaign_repository campaign_store_root].map { |key| fixed.fetch(key) }).each do |path|
               wire.root_path!(path, directory: true, owner: service.fetch("uid"))
               unless (File.stat(path).mode & 0o077).zero?
                 raise Ace::Runtime::RuntimeUnavailableError, "authority state root must remain private"

data/lib/ace/assign/authority/deployment_history.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "deployment"
+
+module Ace
+  module Assign
+    module Authority
+      # Immutable installer configuration, indexed by canonical content identity.
+      # This object is never a transport selector or an execution ledger.
+      class DeploymentHistory
+        PATH = "/etc/ace/assignment-deployment-history.json"
+        attr_reader :original, :candidate, :artifact_reference
+
+        def self.load = load_protected(nil)
+
+        def self.load_artifact(reference)
+          validate_reference!(reference)
+          load_protected(reference)
+        end
+
+        def self.load_protected(reference)
+          Ace::Runtime::Molecules::ProtectedArtifactSet.new.with do |artifacts|
+            bytes = if reference
+              artifacts.read!(reference)
+            else
+              held, selected = artifacts.read_path!(PATH, limit: 65_536)
+              reference = selected
+              held
+            end
+            raw = bytes.dup.force_encoding(Encoding::UTF_8)
+            raise ArgumentError, "history manifest is not UTF-8" unless raw.valid_encoding?
+            value = JSON.parse(raw, create_additions: false, max_nesting: 32,
+              allow_duplicate_key: false, allow_comments: false)
+            unless value.is_a?(Hash) && value.keys.sort ==
+                %w[candidate_descriptor descriptors original_descriptor public_keys schema] &&
+                value["schema"] == "ace.assign.deployment-history/v1"
+              raise ArgumentError, "invalid deployment history manifest"
+            end
+            descriptors = value.fetch("descriptors")
+            keys = value.fetch("public_keys")
+            unless descriptors.is_a?(Array) && descriptors.size.between?(1, 128) &&
+                keys.is_a?(Array) && keys.size <= 128 && descriptors.size + keys.size <= 255
+              raise ArgumentError, "deployment history inventory exceeds bounds"
+            end
+            index = {}
+            descriptors.each do |selected|
+              validate_reference!(selected)
+              digest = selected.fetch("sha256")
+              raise ArgumentError, "duplicate historical descriptor selector" if index.key?(digest)
+              index[digest] = Deployment.send(:from_verified_bytes, artifacts.read!(selected), immutable(selected))
+            end
+            selections = %w[original_descriptor candidate_descriptor].map do |name|
+              selected = value.fetch(name)
+              validate_reference!(selected)
+              descriptor = index.fetch(selected.fetch("sha256")) do
+                raise ArgumentError, "transaction descriptor is not retained"
+              end
+              unless descriptor.artifact_reference == selected
+                raise ArgumentError, "transaction descriptor reference conflicts"
+              end
+              descriptor
+            end
+            public_keys = {}
+            keys.each do |entry|
+              unless entry.is_a?(Hash) && entry.keys.sort == %w[public_key_sha256 ref] &&
+                  digest?(entry["public_key_sha256"])
+                raise ArgumentError, "invalid historical public key entry"
+              end
+              validate_reference!(entry.fetch("ref"))
+              digest = entry.fetch("public_key_sha256")
+              raise ArgumentError, "duplicate historical public key selector" if public_keys.key?(digest)
+              key = OpenSSL::PKey.read(artifacts.read!(entry.fetch("ref")))
+              unless key.is_a?(OpenSSL::PKey::RSA) && !key.private? &&
+                  Digest::SHA256.hexdigest(key.public_key.to_der) == digest
+                raise ArgumentError, "historical public key identity differs"
+              end
+              public_keys[digest] = key.freeze
+            end
+            selections.first.maintenance_inventory(selections.last)
+            history = new(selections, index, public_keys, immutable(reference))
+            artifacts.verify_unchanged!
+            history.freeze
+          end
+        end
+
+        def initialize(selections, descriptors, keys, reference)
+          @original, @candidate = selections
+          @descriptors, @keys = descriptors.freeze, keys.freeze
+          @artifact_reference = reference
+        end
+        private_class_method :new
+
+        def descriptor!(sha256:)
+          @descriptors.fetch(sha256) do
+            raise AttemptErrors::EvidenceUnavailable, "original protected descriptor is not retained"
+          end
+        end
+
+        def public_key!(sha256:)
+          @keys.fetch(sha256) do
+            raise AttemptErrors::EvidenceUnavailable, "original protected public key is not retained"
+          end
+        end
+
+        def descriptors = @descriptors.values.freeze
+
+        # Publication moves verified bytes to the fixed current descriptor path.
+        # Retention paths stay immutable; canonical content, not pathname, joins
+        # the installed selection to that exact independently verified artifact.
+        def selects?(deployment, selection: nil)
+          return false unless deployment.is_a?(Deployment) && deployment.frozen? && deployment.artifact_reference
+          choices = case selection
+          when :original then [original]
+          when :candidate then [candidate]
+          when nil then [original, candidate]
+          else raise ArgumentError, "invalid history transaction selection"
+          end
+          choices.any? do |selected|
+            selected.artifact_reference.values_at("sha256", "bytes") == deployment.artifact_reference.values_at("sha256", "bytes")
+          end
+        end
+
+        def self.digest?(value) = value.is_a?(String) && value.match?(/\A[0-9a-f]{64}\z/)
+
+        def self.validate_reference!(value)
+          unless value.is_a?(Hash) && value.keys.sort == %w[bytes path sha256] &&
+              value["path"].is_a?(String) && value["path"].start_with?("/") &&
+              !value["path"].include?("\0") && File.expand_path(value["path"]) == value["path"] &&
+              digest?(value["sha256"]) && value["bytes"].is_a?(Integer) && value["bytes"].between?(1, 65_536)
+            raise ArgumentError, "invalid protected history artifact reference"
+          end
+        end
+
+        def self.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
+        private_class_method :digest?, :validate_reference!, :immutable, :load_protected
+      end
+    end
+  end
+end