ace-assign 0.64.0 → 0.66.1

data/lib/ace/assign/models/evidence_event.rb

@@ -15,10 +15,10 @@ module Ace
       # metadata only.
       module EvidenceEvent
         TYPES = %w[
-          intent process_start receipt_accepted transition
+          intent process_start receipt_accepted transition attempt_stopped
           candidate_invalidated reconciliation
-          service_claim service_transition recovery_observation inbox_binding inbox_reconciliation delivery
-          authority_mutation evidence_import proposal_state result_submitted
+          service_claim service_transition service_challenge service_no_effect_challenge service_publication_challenge service_publication_issuing recovery_observation inbox_binding delivery
+          authority_mutation evidence_import proposal_state result_submitted prompt_issued prompt_outcome prompt_completion_observed input_inhibited
           scope_provisioning scope_bound scope_native_bound scope_child_bound scope_sealed scope_closed_no_writers
         ].freeze
 

data/lib/ace/assign/molecules/assignment_manager.rb

@@ -13,7 +13,8 @@ module Ace
       # Uses ace-b36ts for assignment ID generation.
       class AssignmentManager
         # @param cache_base [String] Base cache directory
-        def initialize(cache_base: nil)
+        def initialize(cache_base: nil, selected_assignment: nil)
+          @selected_assignment = selected_assignment
           @cache_base = cache_base || Ace::Assign.cache_dir
         end
 
@@ -85,6 +86,7 @@ module Ace
         #
         # @return [Models::Assignment, nil] Most recent assignment or nil
         def find_active
+          return @selected_assignment if @selected_assignment
           return nil unless File.directory?(@cache_base)
 
           # Priority 1: use .current symlink if it exists (explicit selection)
@@ -185,6 +187,7 @@ module Ace
           )
 
           write_assignment_file(updated)
+          @selected_assignment = updated if @selected_assignment && @selected_assignment.id == updated.id
 
           # Update .latest symlink since this assignment was just updated
           update_latest_symlink(assignment.id)
@@ -259,7 +262,14 @@ module Ace
 
         def write_assignment_file(assignment)
           assignment_file = File.join(assignment.cache_dir, "assignment.yaml")
-          File.write(assignment_file, assignment.to_h.to_yaml)
+          if @selected_assignment
+            File.open(assignment_file, File::WRONLY | File::TRUNC | File::NOFOLLOW | File::NONBLOCK) do |file|
+              raise ArgumentError, "selected assignment metadata is not regular" unless file.stat.file?
+              file.write(assignment.to_h.to_yaml); file.flush; file.fsync
+            end
+          else
+            File.write(assignment_file, assignment.to_h.to_yaml)
+          end
         end
 
         def load_from_file(assignment_file)

data/lib/ace/assign/molecules/attempt_reconciler.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+require_relative "canonical_attempt_state"
 
 require "json"
 
@@ -19,6 +20,21 @@ module Ace
       # effects are never retried automatically, and an uncertain attempt
       # without a receipt stays uncertain.
       class AttemptReconciler
+        # The protected boundary supplies authenticated original scope facts
+        # and exact kernel identities; never a runtime discovered by pane name.
+        def self.protected_observation(kernel:, binding:, observer:, lineage:)
+          return {"liveness" => "unknown"} if lineage.sealed?
+          kernel.live!(binding.fetch("process_identity"))
+          kernel.live!(binding.fetch("native_origin").fetch("server_identity"))
+          observation = observer.observe(lineage)
+          unless observation.is_a?(Hash) && observation["populated"].is_a?(Integer) && observation["populated"].positive?
+            return {"liveness" => "unknown"}
+          end
+          {"liveness" => "live", "identity" => binding.fetch("process_identity"), "runtime_binding" => binding}
+        rescue AttemptErrors::EvidenceUnavailable, Ace::Runtime::RuntimeUnavailableError
+          {"liveness" => "unknown"}
+        end
+
         # @param journal [EvidenceJournal, nil] Managed evidence journal
         # @param verifier [ReceiptVerifier, nil] Receipt verifier (coordinator supplies on use)
         def initialize(journal: nil, verifier: nil, observer: nil, runtime_resolver: Ace::Runtime)
@@ -33,6 +49,10 @@ module Ace
         # @param attempt [Models::Attempt] Running attempt
         # @return [Symbol] :stopped, :live, or :uncertain
         def classify(attempt)
+          events = events_for(attempt)
+          if events.any? { |event| event["type"] == "attempt_stopped" } && CanonicalAttemptState.derive(events) == "stopped"
+            return :stopped
+          end
           return :live if process_live?(attempt)
           :uncertain
         end

data/lib/ace/assign/molecules/canonical_attempt_state.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative "execution_scope_lineage"
+require_relative "../atoms/attempt_state_machine"
+
+module Ace
+  module Assign
+    module Molecules
+      # Canonical state projection, not live closure or settlement authority.
+      # The stopped producer and terminal consumer must additionally obtain the
+      # existing owners' authenticated original-prefix evidence and fresh proof.
+      module CanonicalAttemptState
+        STOPPED_FIELDS = %w[project_id mapping_id assignment_id attempt_id descriptor_sha256
+          scope_binding_event_id seal_event_id closed_proof_event_id service_settlement_event_digests].freeze
+        SELECTION_FIELDS = (STOPPED_FIELDS - %w[service_settlement_event_digests]).freeze
+
+        def self.derive(events)
+          return nil unless events.any? { |event| event["type"] == "intent" }
+          state = "reserved"
+          stopped = false
+          events.each do |event|
+            if stopped && %w[process_start receipt_accepted transition reconciliation attempt_stopped].include?(event["type"])
+              unavailable!("Accepted stopped attempt cannot be resurrected or replaced")
+            end
+            case event["type"]
+            when "process_start" then state = "running"
+            when "receipt_accepted" then state = event.dig("payload", "receipt", "verdict") || state
+            when "transition" then state = event.dig("payload", "to") || state
+            when "reconciliation" then state = event.dig("payload", "resolution") || state
+            when "attempt_stopped"
+              verify_stopped_acceptance!(events, event, prior_state: state)
+              state = "stopped"
+              stopped = true
+            end
+          end
+          state
+        end
+
+        def self.stopped_payload!(events:, selection:, service_evidence:, commit:)
+          unless selection.is_a?(Hash) && selection.keys.sort == SELECTION_FIELDS.sort &&
+              service_evidence.is_a?(Hash) && service_evidence.keys.sort == %w[commit services] &&
+              commit.is_a?(String) && commit.match?(/\A(?:[0-9a-f]{40}|[0-9a-f]{64})\z/) &&
+              service_evidence["commit"] == commit
+            unavailable!("Stopped plan evidence prefix differs")
+          end
+          services = service_evidence.fetch("services")
+          unless services.is_a?(Array) &&
+              services.all? { |item| item.is_a?(Hash) && item.keys.sort == %w[event_digest evidence_refs receipt_digest record_digest request_id state] }
+            unavailable!("Stopped settlement projections are malformed")
+          end
+          service_ids = services.map { |item| item.fetch("request_id") }
+          unless service_ids == service_ids.sort && service_ids.uniq == service_ids
+            unavailable!("Stopped settlement projection is not ordered unique owner output")
+          end
+          services.each do |item|
+            event = events.find { |entry| entry["digest"] == item.fetch("event_digest") && entry["type"] == "service_transition" }
+            unless event && event.dig("payload", "request_id") == item.fetch("request_id") &&
+                event.dig("payload", "state") == item.fetch("state") && %w[succeeded failed-settled].include?(item.fetch("state")) &&
+                event.dig("payload", "record_digest") == item.fetch("record_digest") &&
+                event.dig("payload", "receipt_digest") == item.fetch("receipt_digest")
+              unavailable!("Stopped service projection differs from canonical terminal event")
+            end
+          end
+          payload = selection.merge("service_settlement_event_digests" => services.map { |item| item.fetch("event_digest") }.sort)
+          validate_stopped_payload!(events, payload)
+          payload
+        rescue KeyError, TypeError, ArgumentError, NoMethodError
+          unavailable!("Stopped plan evidence is malformed")
+        end
+
+        def self.verify_stopped_acceptance!(events, event, prior_state:)
+          Atoms::AttemptStateMachine.proof_stopped_transition!(prior_state)
+          unless events.count { |entry| entry["type"] == "attempt_stopped" } == 1 && Models::EvidenceEvent.chain_valid?(events)
+            unavailable!("Stopped canonical chain is ambiguous or corrupt")
+          end
+          payload = event.fetch("payload")
+          prefix = events.take_while { |entry| entry["digest"] != event.fetch("digest") }
+          validate_stopped_payload!(prefix, payload)
+          acceptance = events.find { |entry| entry["type"] == "authority_mutation" && entry["previous_digest"] == event.fetch("digest") }
+          data = acceptance&.dig("payload", "data")
+          generation = acceptance && events.take_while { |entry| entry["digest"] != acceptance["digest"] }.count { |entry| entry["type"] == "authority_mutation" } + 1
+          unless acceptance && data.is_a?(Hash) && data.keys.sort == %w[attempt_id generation proof_id required_action state] &&
+              data["generation"].is_a?(Integer) && data["generation"] == generation &&
+              acceptance.dig("payload", "operation") == "stop_attempt" &&
+              acceptance.dig("payload", "assignment_id") == payload.fetch("assignment_id") &&
+              acceptance.dig("payload", "attempt_id") == payload.fetch("attempt_id") &&
+              acceptance.dig("payload", "data", "attempt_id") == payload.fetch("attempt_id") &&
+              acceptance.dig("payload", "data", "state") == "stopped" &&
+              acceptance.dig("payload", "data", "proof_id") == payload.fetch("closed_proof_event_id") &&
+              acceptance.dig("payload", "data", "required_action").nil?
+            unavailable!("Stopped transition has no adjacent accepted owner mutation")
+          end
+          seal = prefix.find { |entry| entry["digest"] == payload.fetch("seal_event_id") }
+          accepted_seal = seal && prefix.find { |entry| entry["type"] == "authority_mutation" && entry["previous_digest"] == seal["digest"] &&
+            %w[close_execution_scope stop_attempt].include?(entry.dig("payload", "operation")) }
+          proof = prefix.find { |entry| entry["digest"] == payload.fetch("closed_proof_event_id") }
+          accepted_proof = proof && prefix.find { |entry| entry["type"] == "authority_mutation" && entry["previous_digest"] == proof["digest"] &&
+            %w[close_execution_scope stop_attempt].include?(entry.dig("payload", "operation")) &&
+            entry.dig("payload", "data", "proof_id") == proof["digest"] &&
+            (entry.dig("payload", "operation") == "close_execution_scope" ?
+              entry.dig("payload", "data", "state") == "closed_no_writers" :
+              entry.dig("payload", "data").is_a?(Hash) && entry.dig("payload", "data").keys.sort == %w[attempt_id generation proof_id required_action state] &&
+                entry.dig("payload", "data", "attempt_id") == payload.fetch("attempt_id") &&
+                entry.dig("payload", "data", "generation").is_a?(Integer) &&
+                entry.dig("payload", "data", "generation") == prefix.take_while { |item| item["digest"] != entry["digest"] }.count { |item| item["type"] == "authority_mutation" } + 1 &&
+                entry.dig("payload", "data", "state") == "uncertain" &&
+                entry.dig("payload", "data", "required_action") == "reconcile_scope") }
+          unless accepted_seal && (accepted_proof || event["previous_digest"] == proof&.fetch("digest"))
+            unavailable!("Stopped canonical seal or proof has no accepted owner")
+          end
+          event
+        rescue KeyError, TypeError, ArgumentError, NoMethodError, AttemptErrors::InvalidTransition
+          unavailable!("Stopped canonical acceptance is malformed")
+        end
+
+        def self.validate_stopped_payload!(events, payload)
+          unless payload.is_a?(Hash) && payload.keys.sort == STOPPED_FIELDS.sort &&
+              %w[project_id mapping_id assignment_id attempt_id].all? { |key| payload[key].is_a?(String) && ExecutionScopeLineage::ID.match?(payload[key]) } &&
+              %w[descriptor_sha256 scope_binding_event_id seal_event_id closed_proof_event_id].all? { |key| digest?(payload[key]) } &&
+              %w[service_settlement_event_digests].all? { |key|
+                values = payload[key]
+                values.is_a?(Array) && values.all? { |value| digest?(value) } && values == values.sort && values.uniq == values }
+            unavailable!("Stopped canonical payload is not closed")
+          end
+          lineage = ExecutionScopeLineage.new(events: events, **payload.slice("project_id", "mapping_id", "assignment_id", "attempt_id").transform_keys(&:to_sym))
+          provisioning = events.select { |event| event["type"] == "scope_provisioning" }
+          unless provisioning.one? && provisioning.first.dig("payload", "descriptor_sha256") == payload.fetch("descriptor_sha256") &&
+              lineage.native_event && lineage.child_event &&
+              lineage.binding_event&.fetch("digest") == payload.fetch("scope_binding_event_id") &&
+              lineage.seal_event&.fetch("digest") == payload.fetch("seal_event_id") &&
+              lineage.proof_event&.fetch("digest") == payload.fetch("closed_proof_event_id")
+            unavailable!("Stopped canonical original scope selectors differ")
+          end
+          payload.fetch("service_settlement_event_digests").each do |digest|
+            unless events.any? { |event| event["digest"] == digest && event["type"] == "service_transition" &&
+                %w[succeeded failed-settled].include?(event.dig("payload", "state")) }
+              unavailable!("Stopped canonical service selector is not terminal evidence")
+            end
+          end
+          payload
+        rescue KeyError, TypeError, ArgumentError, NoMethodError
+          unavailable!("Stopped canonical scope is malformed")
+        end
+
+        def self.digest?(value) = value.is_a?(String) && ExecutionScopeLineage::DIGEST.match?(value)
+        def self.unavailable!(message) = raise AttemptErrors::EvidenceUnavailable, message
+        private_class_method :digest?, :unavailable!
+      end
+    end
+  end
+end

data/lib/ace/assign/molecules/canonical_evidence.rb

@@ -14,8 +14,8 @@ module Ace
         MAX_TOTAL_BYTES = 256 * 1024
         MAX_ARTIFACTS = 16
         ID = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
-        ROLES = {"service" => "executor", "review" => "reviewer", "inbox" => "signer",
-                 "observation" => "observer", "result" => "worker"}.freeze
+        ROLES = {"service" => "executor", "review" => "reviewer",
+                 "result" => "worker"}.freeze
         DESCRIPTOR_FIELDS = %w[version artifact_id kind project_id assignment_id attempt_id peer_uid role
           binding_digest sha256 bytes admitted_at admitted_after_event_digest request_id_or_event_id
           candidate_generation_or_claim_generation].freeze
@@ -132,6 +132,9 @@ module Ace
             expected.all? { |key, value| descriptor[key] == value }
           before = events.take_while { |entry| entry["digest"] != event["digest"] }
           unavailable! unless before.any? { |entry| entry["digest"] == descriptor["admitted_after_event_digest"] }
+          if kind == "service" && binding["no_effect_challenge"]
+            unavailable! unless descriptor["admitted_after_event_digest"] == binding.fetch("challenge_event_digest")
+          end
           Time.iso8601(descriptor.fetch("admitted_at"))
           bytes = yield(reference.fetch("ref"))
           unavailable! unless bytes.is_a?(String) && bytes.bytesize <= MAX_ARTIFACT_BYTES && bytes.bytesize == descriptor["bytes"] &&

data/lib/ace/assign/molecules/canonical_read_snapshot.rb

@@ -0,0 +1,374 @@
+# frozen_string_literal: true
+
+require "digest"
+require "fileutils"
+require "tmpdir"
+require "ace/herdr/molecules/bounded_process"
+require_relative "evidence_journal"
+require_relative "../authority/private_directory"
+
+module Ace
+  module Assign
+    module Molecules
+      # Isolates read-only Git from an installed authority's live configuration.
+      # The copied view never publishes evidence or mutates the source journal.
+      class CanonicalReadSnapshot
+        class Unavailable < AttemptErrors::EvidenceUnavailable; end
+        BYTE_LIMIT = 256 * 1_048_576
+        ENTRY_LIMIT = 4096
+        OID = /\A[0-9a-f]{40}\z/
+        ENVIRONMENT = {"PATH" => "/usr/bin:/bin", "LC_ALL" => "C",
+          "GIT_CONFIG_NOSYSTEM" => "1", "GIT_CONFIG_SYSTEM" => "/dev/null",
+          "GIT_CONFIG_GLOBAL" => "/dev/null", "GIT_TERMINAL_PROMPT" => "0",
+          "GIT_ALLOW_PROTOCOL" => "", "GIT_NO_REPLACE_OBJECTS" => "1",
+          "GIT_NO_LAZY_FETCH" => "1", "GIT_OPTIONAL_LOCKS" => "0"}.freeze
+
+        # These selections come from installed source composition, not frames.
+        def initialize(repo_root:, checkout_root:, ref:, private_root:, git_executable: "/usr/bin/git")
+          paths = [repo_root, checkout_root, private_root, git_executable]
+          unless paths.all? { |path| path.is_a?(String) && path.start_with?("/") &&
+              !path.include?("\0") && File.expand_path(path) == path } &&
+              ref.is_a?(String) && ref.match?(/\Arefs\/[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)+\z/)
+            raise ArgumentError, "canonical snapshot source selection is malformed"
+          end
+          @repo_root, @checkout_root, @private_root, @git = paths.map { |path| path.dup.freeze }
+          @ref = ref.dup.freeze
+          @verification = Mutex.new
+        end
+
+        def with(deadline:)
+          refuse!("snapshot_busy") unless @verification.try_lock
+          begin
+            with_snapshot(deadline: deadline) { |snapshot| yield snapshot }
+          ensure
+            @verification.unlock
+          end
+        end
+
+        def with_snapshot(deadline:)
+          validate_deadline!(deadline)
+          verify_private_root!
+          private_stat = directory!(@private_root)
+          unless private_stat.uid == Process.uid && (private_stat.mode & 0o7777) == 0o700
+            refuse!("private_storage_unprotected")
+          end
+          Dir.mktmpdir("canonical-read-", @private_root) do |view|
+            verify_private_root!
+            refuse!("private_storage_unprotected") unless directory_identity(File.lstat(@private_root)) == directory_identity(private_stat)
+            @view, @deadline = view, deadline
+            @held, @directories, @inventory, @inventory_files, @metadata_files = [], [], [], [], []
+            @bytes, @entries = 0, 0
+            git_dir = File.join(@repo_root, ".git")
+            directory!(git_dir)
+            %w[commondir reftable shallow].each do |name|
+              refuse!("unsupported_source") if exists?(File.join(git_dir, name))
+            end
+            lock, original_lock = held_file!(File.join(@checkout_root, ".evidence.lock"), limit: 128)
+            begin
+              acquire!(lock)
+              begin
+                source_config!(git_dir)
+                @commit = select_ref!(git_dir)
+                objects = File.join(git_dir, "objects")
+                inventory = inventory!(objects)
+                inventory.each { |relative, handle| copy!(relative, handle) }
+                verify_held!
+                refuse!("source_changed") unless inventory_names!(objects) == @inventory &&
+                  select_ref!(git_dir) == @commit && identity(File.lstat(lock.path)) == original_lock
+                verify_held!
+              ensure
+                lock.flock(File::LOCK_UN)
+              end
+            end
+            prepare_view!
+            run!(%w[fsck --full --strict --no-reflogs], limit: 65_536)
+            yield self
+          ensure
+            @held&.each { |handle| handle.close unless handle.closed? }
+            @held = @directories = @inventory = @inventory_files = @metadata_files = @view = @deadline = @commit = nil
+          end
+        rescue Timeout::Error
+          refuse!("resource_limit")
+        rescue IOError, SystemCallError, Herdr::Molecules::BoundedProcess::PostLaunchError
+          refuse!("source_unavailable")
+        end
+        private :with_snapshot
+
+        attr_reader :commit
+
+        # EvidenceJournal uses this only as its existing read command boundary.
+        def call(argv, stdin_data: "", output_limit: BYTE_LIMIT)
+          refuse!("read_outside_snapshot") unless @view && @commit
+          unless read_command?(argv, stdin_data)
+            refuse!("write_or_unsupported_command")
+          end
+          result = run!(argv, stdin_data: stdin_data, limit: [output_limit, BYTE_LIMIT].min)
+          [result.stdout.to_s.strip, result.stderr.to_s.strip, result.status]
+        end
+
+        def blob_batch(entries, output_limit:)
+          refuse!("read_outside_snapshot") unless @view && @commit
+          unless entries.is_a?(Array) && entries.all? { |oid| oid.is_a?(String) && oid.match?(OID) }
+            refuse!("unsupported_command")
+          end
+          result = run!(["cat-file", "--batch"], stdin_data: entries.join("\n") + "\n",
+            limit: [output_limit, BYTE_LIMIT].min)
+          result.stdout.to_s.b
+        end
+
+        def history_diff(commits, paths, output_limit:)
+          refuse!("read_outside_snapshot") unless @view && @commit
+          unless commits.is_a?(Array) && commits.size.between?(1, 64) && commits.uniq.size == commits.size &&
+              commits.all? { |commit| commit.is_a?(String) && commit.match?(OID) } &&
+              paths.is_a?(Array) && !paths.empty? && paths.uniq.size == paths.size &&
+              (paths == ["execution/"] || paths.all? { |path| path.is_a?(String) && path.match?(%r{\Aexecution/[a-zA-Z0-9_.:-]+/events/\z}) }) &&
+              output_limit.is_a?(Integer) && output_limit.positive?
+            refuse!("unsupported_command")
+          end
+          result = run!(%w[diff-tree --stdin --always --root -r --raw -z --no-renames --no-ext-diff
+            --no-textconv --no-abbrev --] + paths, stdin_data: commits.join("\n") + "\n",
+            limit: [output_limit, BYTE_LIMIT].min)
+          result.stdout.to_s.b
+        end
+
+        def blob_sizes(oids)
+          refuse!("read_outside_snapshot") unless @view && @commit
+          unless oids.is_a?(Array) && oids.size.between?(1, 64) && oids.all? { |oid| oid.is_a?(String) && oid.match?(OID) }
+            refuse!("unsupported_command")
+          end
+          run!(%w[cat-file --batch-check], stdin_data: oids.join("\n") + "\n", limit: oids.size * 128).stdout.to_s.b
+        end
+
+        def blob(path, commit:, max_bytes:)
+          refuse!("read_outside_snapshot") unless @view && @commit
+          unless commit.is_a?(String) && commit.match?(OID) && max_bytes.is_a?(Integer) && max_bytes.positive?
+            refuse!("unsupported_command")
+          end
+          result = run!(["cat-file", "blob", "#{commit}:#{path}"], limit: [max_bytes, BYTE_LIMIT].min)
+          result.stdout.to_s.b
+        end
+
+        private
+
+        def refuse!(reason)
+          raise Unavailable, "canonical read snapshot unavailable: #{reason}"
+        end
+
+        def validate_deadline!(deadline)
+          unless deadline.is_a?(Numeric) && deadline.finite? && deadline > Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            refuse!("resource_limit")
+          end
+        end
+
+        def remaining
+          value = @deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          refuse!("resource_limit") unless value.positive?
+          value
+        end
+
+        def acquire!(lock)
+          until lock.flock(File::LOCK_SH | File::LOCK_NB)
+            sleep [remaining, 0.005].min
+          end
+        end
+
+        def identity(stat)
+          [stat.dev, stat.ino, stat.mode, stat.uid, stat.gid, stat.size, stat.mtime, stat.ctime]
+        end
+
+        def verify_private_root!
+          Authority::PrivateDirectory.verify!(@private_root)
+        rescue AttemptErrors::ReceiptRejected
+          refuse!("private_storage_unprotected")
+        end
+
+        def directory_identity(stat)
+          [stat.dev, stat.ino, stat.mode, stat.uid, stat.gid]
+        end
+
+        def directory!(path)
+          stat = File.lstat(path)
+          refuse!("unsupported_source") unless stat.directory? && !stat.symlink?
+          stat
+        end
+
+        def exists?(path)
+          File.lstat(path)
+          true
+        rescue Errno::ENOENT
+          false
+        end
+
+        def held_file!(path, limit:)
+          remaining
+          parent = File.dirname(path)
+          until parent == "/"
+            stat = directory!(parent)
+            @directories << [parent, directory_identity(stat)]
+            parent = File.dirname(parent)
+          end
+          handle = File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+          @held << handle
+          stat = handle.stat
+          refuse!("unsupported_source") unless stat.file?
+          refuse!("resource_limit") if stat.size > limit
+          [handle, identity(stat)]
+        end
+
+        def select_ref!(git_dir)
+          loose = File.join(git_dir, @ref)
+          if exists?(loose)
+            handle, before = held_file!(loose, limit: 128)
+            bytes = handle.read(129)
+            @metadata_files << [loose, handle, before]
+            refuse!("source_changed") unless identity(handle.stat) == before
+            refuse!("unsupported_ref") unless bytes.match?(/\A[0-9a-f]{40}\n?\z/)
+            return bytes.strip
+          end
+          packed = File.join(git_dir, "packed-refs")
+          handle, before = held_file!(packed, limit: 65_536)
+          bytes = handle.read(65_537)
+          @metadata_files << [packed, handle, before]
+          refuse!("source_changed") unless identity(handle.stat) == before
+          entries = {}
+          bytes.lines.each do |line|
+            next if line.start_with?("#") || line.match?(/\A\^[0-9a-f]{40}\n?\z/)
+            match = /\A([0-9a-f]{40}) (refs\/[^\s\0]+)\n?\z/.match(line)
+            refuse!("unsupported_ref") unless match && !entries.key?(match[2])
+            entries[match[2]] = match[1]
+          end
+          entries.fetch(@ref) { refuse!("unsupported_ref") }
+        end
+
+        def source_config!(git_dir)
+          path = File.join(git_dir, "config")
+          handle, before = held_file!(path, limit: 65_536)
+          bytes = handle.read(65_537)
+          @metadata_files << [path, handle, before]
+          refuse!("source_changed") unless identity(handle.stat) == before
+          # Standalone file parsing does not select the target repository,
+          # follow includes or execute aliases/hooks/helpers. No source config
+          # is installed into the private administrative view.
+          result = run!(["config", "--no-includes", "--null", "--list", "--file", "/dev/stdin"],
+            stdin_data: bytes, limit: 65_536)
+          versions = []
+          result.stdout.split("\0").each do |entry|
+            key, value = entry.split("\n", 2)
+            refuse!("unsupported_source") if key.start_with?("extensions.") || key == "core.worktree"
+            versions << value if key == "core.repositoryformatversion"
+          end
+          refuse!("unsupported_source") unless versions.empty? || versions == ["0"]
+        end
+
+        def inventory_names!(objects)
+          names = []
+          walk = lambda do |path, relative|
+            remaining
+            stat = File.lstat(path)
+            names << [relative, stat.directory? ? "directory" : "file"]
+            refuse!("resource_limit") if names.size > ENTRY_LIMIT
+            refuse!("unsupported_source") if stat.symlink? || !(stat.directory? || stat.file?)
+            if stat.directory?
+              unless relative.empty? || %w[pack info].include?(relative) || relative.match?(/\A[0-9a-f]{2}\z/)
+                refuse!("unsupported_source")
+              end
+              children = []
+              Dir.each_child(path) do |name|
+                remaining
+                children << name
+                refuse!("resource_limit") if children.size + names.size > ENTRY_LIMIT
+              end
+              children.sort.each { |name| walk.call(File.join(path, name), relative.empty? ? name : "#{relative}/#{name}") }
+            end
+          end
+          walk.call(objects, "")
+          names
+        end
+
+        def inventory!(objects)
+          @inventory = inventory_names!(objects)
+          files = @inventory.select { |_relative, kind| kind == "file" }.map(&:first)
+          packs = files.grep(/\Apack\/pack-[0-9a-f]{40}\.pack\z/)
+          unless packs.all? { |pack| files.include?(pack.sub(/\.pack\z/, ".idx")) } &&
+              files.grep(/\Apack\/pack-[0-9a-f]{40}\.(?:idx|rev)\z/).all? { |file| packs.include?(file.sub(/\.(?:idx|rev)\z/, ".pack")) }
+            refuse!("unsupported_source")
+          end
+          @inventory.filter_map do |relative, kind|
+            path = relative.empty? ? objects : File.join(objects, relative)
+            if kind == "directory"
+              unless relative.empty? || relative == "pack" || relative == "info" || relative.match?(/\A[0-9a-f]{2}\z/)
+                refuse!("unsupported_source")
+              end
+              @directories << [path, directory_identity(File.lstat(path))]
+              next
+            end
+            # These ordinary Git indexes/retention hints do not redirect
+            # storage. The clean view never reads them; only object bytes and
+            # pack indexes are copied. Redirect/lazy-fetch metadata refuses.
+            next if relative.match?(/\Ainfo\/(?:packs|commit-graph)\z/) ||
+              relative.match?(/\Apack\/pack-[0-9a-f]{40}\.(?:bitmap|keep)\z/)
+            unless relative.match?(/\A[0-9a-f]{2}\/[0-9a-f]{38}\z/) ||
+                relative.match?(/\Apack\/pack-[0-9a-f]{40}\.(?:pack|idx|rev)\z/)
+              refuse!("unsupported_source")
+            end
+            handle, before = held_file!(path, limit: BYTE_LIMIT)
+            @bytes += handle.stat.size
+            refuse!("resource_limit") if @bytes > BYTE_LIMIT
+            @inventory_files << [path, handle, before]
+            [relative, handle]
+          end
+        end
+
+        def copy!(relative, source)
+          destination = File.join(@view, "objects", relative)
+          FileUtils.mkdir_p(File.dirname(destination), mode: 0o700)
+          File.open(destination, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |target|
+            copied = 0
+            expected = source.stat.size
+            while (chunk = source.read(65_536))
+              remaining
+              copied += chunk.bytesize
+              refuse!("source_changed") if copied > expected
+              target.write(chunk)
+            end
+            refuse!("source_changed") unless copied == expected
+          end
+        end
+
+        def verify_held!
+          @directories.each { |path, before| refuse!("source_changed") unless directory_identity(File.lstat(path)) == before }
+          (@inventory_files + @metadata_files).each do |path, handle, before|
+            refuse!("source_changed") unless identity(handle.stat) == before && identity(File.lstat(path)) == before
+          end
+        end
+
+        def prepare_view!
+          FileUtils.mkdir_p(File.join(@view, "objects"), mode: 0o700)
+          FileUtils.mkdir_p(File.join(@view, "refs"), mode: 0o700)
+          File.binwrite(File.join(@view, "HEAD"), "#{@commit}\n")
+          File.binwrite(File.join(@view, "config"), "[core]\nrepositoryformatversion = 0\nbare = true\n")
+          ref = File.join(@view, @ref)
+          FileUtils.mkdir_p(File.dirname(ref), mode: 0o700)
+          File.binwrite(ref, "#{@commit}\n")
+        end
+
+        def read_command?(argv, stdin)
+          return false unless argv.is_a?(Array) && argv.all? { |item| item.is_a?(String) && !item.include?("\0") } && stdin.empty?
+          allowed = {"rev-parse" => %w[--verify --quiet --git-dir], "cat-file" => %w[-t -s blob],
+            "rev-list" => %w[--first-parent --parents], "ls-tree" => %w[-r -l -d --name-only --],
+            "show" => [], "log" => %w[--diff-filter=A -1 --format=%H --]}
+          flags = allowed[argv.first]
+          flags && argv.drop(1).all? { |item| !item.start_with?("-") || flags.include?(item) || item == "--max-count=100001" }
+        end
+
+        def run!(argv, stdin_data: "", limit:)
+          result = Herdr::Molecules::BoundedProcess.call([@git, "--git-dir=#{@view}", "--no-pager", *argv],
+            environment: ENVIRONMENT, chdir: @view, stdin_data: stdin_data,
+            timeout_s: remaining, output_limit: limit, stderr_limit: 65_536)
+          refuse!(result.oversized ? "resource_limit" : "git_unavailable") unless result.status.success? && !result.oversized
+          result
+        end
+      end
+    end
+  end
+end