ace-assign 0.64.0 → 0.66.1

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

@@ -5,6 +5,8 @@ require "fileutils"
 require "json"
 require "open3"
 require "time"
+require "securerandom"
+require_relative "../atoms/evidence_digest"
 
 module Ace
   module Assign
@@ -25,6 +27,95 @@ module Ace
       # present. Legitimate fresh provisioning (a new worktree for a task)
       # clears the marker explicitly via `reset_removed`.
       class LifecycleExclusion
+        autoload :ControlExclusion, File.expand_path("protected_control_exclusion", __dir__)
+
+        def self.control_exclusion(authority:, project_id:, descriptor_sha256:, root_identity: nil, **boundaries)
+          ControlExclusion.new(authority: authority, project_id: project_id,
+            descriptor_sha256: descriptor_sha256, root_identity: root_identity, **boundaries)
+        end
+
+        autoload :WorkspaceNativeReader, File.expand_path("protected_workspace_exclusion", __dir__)
+        autoload :WorkspaceReader, File.expand_path("protected_workspace_exclusion", __dir__)
+
+        autoload :WorkspaceWriter, File.expand_path("protected_workspace_exclusion", __dir__)
+
+        autoload :WorkspaceFenceReader, File.expand_path("protected_workspace_exclusion", __dir__)
+
+        def self.workspace_fence_reader(projection:, protection: nil, files: File)
+          WorkspaceFenceReader.new(projection: projection, protection: protection, files: files)
+        end
+
+        def self.workspace_writer(projection:, protection: nil, files: File)
+          WorkspaceWriter.new(projection: projection, protection: protection, files: files)
+        end
+
+        autoload :WorkspaceProvisioner, File.expand_path("protected_workspace_provisioner", __dir__)
+
+        def self.provision_workspace!(mapping_id:, project_id:, authority:, cwd_resource:, **boundaries)
+          WorkspaceProvisioner.new(mapping_id: mapping_id, project_id: project_id,
+            authority: authority, cwd_resource: cwd_resource, **boundaries).provision!
+        end
+
+        def self.workspace_reader(projection:, protection: nil, files: File)
+          WorkspaceReader.new(projection: projection, protection: protection, files: files)
+        end
+
+        def self.workspace_selection(mapping_id:, project_id:, authority:, cwd_resource:)
+          fields = %w[device filesystem_type gid host_path inode mount_id uid view_path]
+          unless authority.is_a?(Hash) && cwd_resource.is_a?(Hash) && cwd_resource.keys.sort == fields &&
+              %w[device gid inode uid].all? { |field| cwd_resource[field].is_a?(Integer) && cwd_resource[field] >= 0 } &&
+              cwd_resource["mount_id"].is_a?(Integer) && cwd_resource["mount_id"].positive? &&
+              %w[host_path view_path].all? { |field| cwd_resource[field].is_a?(String) &&
+                cwd_resource[field].valid_encoding? && cwd_resource[field].bytesize.between?(1, 4096) &&
+                !cwd_resource[field].include?("\0") && cwd_resource[field].start_with?("/") &&
+                File.expand_path(cwd_resource[field]) == cwd_resource[field] } &&
+              %w[ext4 xfs btrfs tmpfs].include?(cwd_resource["filesystem_type"]) &&
+              [mapping_id, project_id].all? { |value| value.is_a?(String) && value.match?(/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/) } &&
+              %w[uid gid].all? { |field| authority[field].is_a?(Integer) && authority[field].positive? } &&
+              authority["state_root"].is_a?(String) && authority["state_root"].valid_encoding? &&
+              authority["state_root"].bytesize.between?(1, 4096) && !authority["state_root"].include?("\0") &&
+              authority["state_root"].start_with?("/") &&
+              File.expand_path(authority["state_root"]) == authority["state_root"]
+            raise AttemptErrors::EvidenceUnavailable, "Original lifecycle workspace selection is malformed"
+          end
+          digest = Atoms::EvidenceDigest.digest(cwd_resource)
+          selection = {"key" => "workspace:#{mapping_id}:#{digest}",
+            "host_path" => File.join(authority.fetch("state_root"), "lifecycle-exclusion", project_id,
+              "workspaces", mapping_id, digest), "view_path" => "/run/ace/lifecycle-exclusion/#{mapping_id}"}
+          unless selection.fetch("host_path").bytesize <= 4096
+            raise AttemptErrors::EvidenceUnavailable, "Original lifecycle workspace path is oversized"
+          end
+          selection.each_value(&:freeze)
+          selection.freeze
+        end
+
+        def self.workspace_initial_marker(key:)
+          unless key.is_a?(String) && key.match?(/\Aworkspace:[A-Za-z0-9][A-Za-z0-9._-]{0,127}:[0-9a-f]{64}\z/)
+            raise AttemptErrors::EvidenceUnavailable, "Original lifecycle workspace key is malformed"
+          end
+          Atoms::EvidenceDigest.canonical_json({"key" => key, "removed" => false, "removed_at" => nil}).freeze
+        end
+
+        def self.workspace_marker!(bytes:, key:)
+          unless bytes.is_a?(String) && bytes.bytesize.between?(1, 8192)
+            raise AttemptErrors::EvidenceUnavailable, "Lifecycle marker bytes differ"
+          end
+          bytes = bytes.dup.force_encoding(Encoding::UTF_8)
+          unless bytes.valid_encoding?
+            raise AttemptErrors::EvidenceUnavailable, "Lifecycle marker is not bounded UTF8"
+          end
+          state = JSON.parse(bytes, create_additions: false, max_nesting: 4, allow_duplicate_key: false)
+          unless state.is_a?(Hash) && state.keys.sort == %w[key removed removed_at] && state.fetch("key") == key &&
+              (state.values_at("removed", "removed_at") == [false, nil] || state["removed"] == true &&
+                state["removed_at"].is_a?(String) && Time.iso8601(state["removed_at"]).utc.iso8601 == state["removed_at"])
+            raise AttemptErrors::EvidenceUnavailable, "Lifecycle marker schema differs"
+          end
+          state.each_value { |value| value.freeze }
+          state.freeze
+        rescue JSON::ParserError, ArgumentError, KeyError
+          raise AttemptErrors::EvidenceUnavailable, "Lifecycle marker schema differs"
+        end
+
         # @param repo_root [String, nil] Repository used to resolve the
         #   shared Git common dir (default: project root)
         # @param root [String, nil] Explicit exclusion root (tests)
@@ -33,21 +124,17 @@ module Ace
         end
 
         # The exclusion root shared by every writer and prune for this repo.
-        # Sandboxed environments (CACHE_BASE) scope it under the cache base,
-        # which itself is never a deletion target; otherwise it lives under
-        # the shared Git common dir, which survives worktree removal.
-        def self.default_root(_repo_root = nil)
-          cache_base = ENV["CACHE_BASE"]
-          if cache_base && !cache_base.empty?
-            return File.join(File.expand_path(cache_base), ".exclusion")
-          end
-
-          repo_root = Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current
+        # Assignment cache configuration does not select this repository
+        # identity. The Git common dir survives linked worktree removal.
+        def self.default_root(repo_root = nil)
+          repo_root ||= Ace::Support::Fs::Molecules::ProjectRootFinder.find_or_current
           common_dir, _stderr, status = Open3.capture3(
             "git", "-C", repo_root, "rev-parse", "--path-format=absolute", "--git-common-dir"
           )
-          base = status.success? && !common_dir.to_s.strip.empty? ? common_dir.strip : File.join(repo_root, ".git")
-          File.join(base, "ace", "lifecycle-exclusion")
+          unless status.success? && !common_dir.to_s.strip.empty? && File.absolute_path(common_dir.strip) == common_dir.strip
+            raise AttemptErrors::Conflict, "Repository lifecycle root is unavailable"
+          end
+          File.join(common_dir.strip, "ace", "lifecycle-exclusion")
         end
 
         def assignment_key(assignment_id)
@@ -79,12 +166,17 @@ module Ace
         #
         # @param key [String] Identity key
         # @yield Required block executed under exclusive exclusion
-        def with_exclusive(key)
+        def with_exclusive(key, deadline: nil)
           raise ArgumentError, "exclusion key is required" if key.to_s.empty?
 
-          lock = open_lock(key)
-          lock.flock(File::LOCK_EX)
+          maintenance_deadline!(deadline) unless deadline.nil?
+          lock = open_lock(key, nonblock: !deadline.nil?)
           begin
+            mode = File::LOCK_EX | (deadline ? File::LOCK_NB : 0)
+            unless lock.flock(mode)
+              raise AttemptErrors::MaintenanceBusy, "maintenance exclusion is busy"
+            end
+            maintenance_deadline!(deadline) unless deadline.nil?
             yield
           ensure
             lock.flock(File::LOCK_UN)
@@ -126,8 +218,9 @@ module Ace
           ordered = Array(keys).compact.reject { |key| key.to_s.empty? }.uniq
           raise ArgumentError, "exclusion keys are required" if ordered.empty?
 
-          locks = ordered.map { |key| open_lock(key) }
+          locks = []
           begin
+            ordered.each { |key| locks << open_lock(key) }
             locks.each { |lock| lock.flock(File::LOCK_SH) }
             ordered.each do |key|
               if removed?(key)
@@ -157,25 +250,67 @@ module Ace
         end
 
         def removed?(key)
-          state = JSON.parse(File.read(state_path(key)))
-          state["removed"] == true
-        rescue Errno::ENOENT, JSON::ParserError, TypeError
+          path = state_path(key)
+          opened = false
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) do |file|
+            opened = true
+            before = file.stat
+            unless before.file? && before.nlink == 1 && before.size.between?(1, 8192) && (before.mode & 0022).zero?
+              raise AttemptErrors::Conflict, "Lifecycle marker is unsafe"
+            end
+            content = file.read(8193).force_encoding(Encoding::UTF_8)
+            unless content.valid_encoding? && content.bytesize == before.size && same_file?(before, file.stat) && same_file?(before, File.lstat(path))
+              raise AttemptErrors::Conflict, "Lifecycle marker changed"
+            end
+            state = JSON.parse(content, create_additions: false, max_nesting: 4, allow_duplicate_key: false)
+            unless state.is_a?(Hash) && state.keys.sort == %w[key removed removed_at] &&
+                state["key"] == key && state["removed"] == true && state["removed_at"].is_a?(String)
+              raise AttemptErrors::Conflict, "Lifecycle marker is malformed"
+            end
+            Time.iso8601(state.fetch("removed_at"))
+            true
+          end
+        rescue Errno::ENOENT
+          raise AttemptErrors::Conflict, "Lifecycle marker disappeared during read" if opened
           false
+        rescue JSON::ParserError, ArgumentError, TypeError, SystemCallError, IOError
+          raise AttemptErrors::Conflict, "Lifecycle marker is unavailable or malformed"
         end
 
         def clear_removed!(key)
+          return unless removed?(key)
           File.delete(state_path(key))
-        rescue Errno::ENOENT
-          nil
+          sync_directory(root)
         end
 
         private
 
         attr_reader :root
 
-        def open_lock(key)
+        def open_lock(key, nonblock: false)
+          retained = false
           FileUtils.mkdir_p(root)
-          File.open(lock_path(key), File::RDWR | File::CREAT)
+          flags = File::RDWR | File::CREAT | File::NONBLOCK | File::NOFOLLOW
+          file = File.open(lock_path(key), flags, 0600)
+          unless file.stat.file? && file.stat.nlink == 1 && (file.stat.mode & 0022).zero? &&
+              same_file?(file.stat, File.lstat(lock_path(key)))
+            raise AttemptErrors::MaintenanceBusy, "maintenance exclusion is not a regular file"
+          end
+          retained = true
+          file
+        rescue SystemCallError
+          raise AttemptErrors::Conflict, "Lifecycle lock is unavailable"
+        ensure
+          file&.close unless retained
+        end
+
+        def maintenance_deadline!(deadline)
+          unless (deadline.is_a?(Integer) || deadline.is_a?(Float)) && deadline.finite?
+            raise ArgumentError, "maintenance deadline must be finite"
+          end
+          if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+            raise AttemptErrors::MaintenanceBusy, "maintenance admission deadline expired"
+          end
         end
 
         def lock_path(key)
@@ -198,15 +333,32 @@ module Ace
           end
         end
 
+        def same_file?(left, right)
+          [left.dev, left.ino, left.size, left.mtime, left.ctime] == [right.dev, right.ino, right.size, right.mtime, right.ctime]
+        end
+
+        def sync_directory(path)
+          File.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK) { |directory| directory.fsync }
+        end
+
         def atomic_write(path, content)
           dir = File.dirname(path)
-          FileUtils.mkdir_p(dir)
-          temp = File.join(dir, ".tmp-#{Process.pid}-#{rand(1_000_000)}")
-          File.write(temp, content)
+          FileUtils.mkdir_p(dir, mode: 0700)
+          temp = File.join(dir, ".tmp-#{SecureRandom.hex(16)}")
+          File.open(temp, File::WRONLY | File::CREAT | File::EXCL | File::NOFOLLOW | File::NONBLOCK, 0600) do |file|
+            file.write(content)
+            file.flush
+            file.fsync
+          end
+          if File.exist?(path) || File.symlink?(path)
+            removed?(JSON.parse(content).fetch("key"))
+          end
           File.rename(temp, path)
+          sync_directory(dir)
         ensure
           File.delete(temp) if temp && File.exist?(temp)
         end
+
       end
     end
   end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "ace/herdr/molecules/guarded_native_origin"
+require_relative "../models/evidence_event"
+
+module Ace
+  module Assign
+    module Molecules
+      # Exact accepted launch record; this reader grants no native effect.
+      module OriginalLaunchBinding
+        def self.verify!(events:, state:, params:)
+          unless state.is_a?(Hash) && state["guarded_origin"].is_a?(Hash) && state["process_binding"].is_a?(Hash)
+            raise AttemptErrors::EvidenceUnavailable, "Original guarded record is unavailable"
+          end
+          unless Models::EvidenceEvent.chain_valid?(events)
+            raise AttemptErrors::EvidenceUnavailable, "Original guarded record chain is corrupt"
+          end
+          records = events.select { |event| event["type"] == "authority_mutation" && event.dig("payload", "operation") == "record_launch" }
+          raise AttemptErrors::EvidenceUnavailable, "Original guarded record is ambiguous or absent" unless records.size == 1
+          record = records.first
+          data = record.fetch("payload").fetch("data")
+          unless data.is_a?(Hash) && record["attempt_id"] == params.fetch("attempt_id") &&
+              %w[mapping_id assignment_id attempt_id].all? { |key| data[key] == params.fetch(key) } &&
+              data["process_binding"] == state.fetch("process_binding") && data["guarded_origin"] == state.fetch("guarded_origin")
+            raise AttemptErrors::EvidenceUnavailable, "Original guarded record differs from accepted launch"
+          end
+          binding = data.fetch("process_binding")
+          origin = Ace::Herdr::Molecules::GuardedNativeOrigin.verify!(data.fetch("guarded_origin"),
+            terminal_id: binding.fetch("terminal_id"), child: binding.fetch("process_identity"))
+          {"binding_digest" => record.fetch("digest").dup.freeze, "origin" => origin}.freeze
+        rescue KeyError, TypeError, Ace::Runtime::RuntimeUnavailableError
+          raise AttemptErrors::EvidenceUnavailable, "Original guarded record is malformed"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require_relative "protected_workspace_exclusion"
+
+module Ace
+  module Assign
+    module Molecules
+      class LifecycleExclusion
+        # Authority-side canonical guards. This owner never selects a Git/cache
+        # root, resets a fence, or grants the lifetime workspace writer lease.
+        class ControlExclusion
+          class Protection < Ace::Runtime::Molecules::ProtectedArtifactSet::Protection
+            def initialize(authority_uid:, acl: Authority::PosixAcl.new, **options)
+              super(**options)
+              @authority_uid, @acl = authority_uid, acl
+            end
+
+            def verify!(path, handle, directory:)
+              super
+              unless (handle.stat.mode & 0o7000).zero? && @acl.entries(path).nil? &&
+                  (!directory || @acl.entries(path, attribute: "system.posix_acl_default").nil?)
+                raise AttemptErrors::EvidenceUnavailable, "Lifecycle control protection differs"
+              end
+            end
+
+            private
+            def trusted_owner?(stat) = [0, @authority_uid].include?(stat.uid)
+          end
+
+          def initialize(authority:, project_id:, descriptor_sha256:, root_identity: nil, files: File, protection: nil)
+            unless authority.is_a?(Hash) && project_id.is_a?(String) && token?(project_id) &&
+                descriptor_sha256.is_a?(String) && descriptor_sha256.match?(/\A[0-9a-f]{64}\z/) &&
+                %w[uid gid].all? { |key| authority[key].is_a?(Integer) && authority[key].positive? } &&
+                authority["state_root"].is_a?(String) && authority["state_root"].valid_encoding? &&
+                authority["state_root"].bytesize.between?(1, 4096) && !authority["state_root"].include?("\0") &&
+                authority["state_root"].start_with?("/") && File.expand_path(authority["state_root"]) == authority["state_root"]
+              unavailable!("Lifecycle control selection is malformed")
+            end
+            @root = File.join(authority.fetch("state_root"), "lifecycle-exclusion", project_id, "control")
+            unavailable!("Lifecycle control path is oversized") if @root.bytesize > 4096
+            @uid, @gid, @descriptor = authority.values_at("uid", "gid") + [descriptor_sha256.dup.freeze]
+            if root_identity
+              unless root_identity.is_a?(Hash) && root_identity.keys.sort == %w[device gid inode uid] &&
+                  root_identity.values.all? { |value| value.is_a?(Integer) && value >= 0 } &&
+                  root_identity.values_at("uid", "gid") == [@uid, @gid]
+                unavailable!("Lifecycle control original identity differs")
+              end
+              @identity = root_identity.dup.freeze
+            end
+            @files = files
+            @protection = protection || Protection.new(authority_uid: @uid)
+          end
+
+          def task_key(id) = key!("task", id)
+          def assignment_key(id) = key!("assignment", id)
+
+          def selection!
+            with_root do |handles, identities|
+              stat = handles.fetch(@root).stat
+              @identity ||= {"device" => stat.dev, "inode" => stat.ino, "uid" => stat.uid, "gid" => stat.gid}.freeze
+              {"descriptor_sha256" => @descriptor, "root_identity" => @identity}.freeze
+            end
+          end
+
+          # Invoked only after the existing complete registration admission.
+          # A partial creation is unavailable, not a missing-fence reset grant.
+          def provision_keys!(keys:)
+            ordered = keys!(keys)
+            with_root do |handles, identities|
+              root = handles.fetch(@root)
+              ordered.each do |key|
+                lock_path, marker_path = paths(key)
+                lock, created = create_or_open!(lock_path, "", root)
+                begin
+                  validate_file!(lock_path, lock, empty: true)
+                  marker = if created
+                    create_or_open!(marker_path, Atoms::EvidenceDigest.canonical_json(
+                      {"key" => key, "removed" => false, "removed_at" => nil}), root).first
+                  else
+                    @files.open(marker_path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+                  end
+                  begin
+                    live_marker!(key, marker_path, marker)
+                  ensure
+                    marker&.close
+                  end
+                ensure
+                  lock&.close
+                end
+                unchanged!(handles, identities)
+              end
+            end
+            self
+          rescue SystemCallError, IOError, Ace::Runtime::RuntimeUnavailableError
+            unavailable!("Lifecycle control provisioning is unavailable")
+          end
+
+          def with_shared_multi(keys, &block) = with_locks(keys, File::LOCK_SH, &block)
+          def with_shared(key, &block) = with_shared_multi([key], &block)
+          def with_exclusive(key, deadline: nil, &block) = with_locks([key], File::LOCK_EX, deadline: deadline, &block)
+
+          # The canonical writer calls this again immediately before CAS. It
+          # authenticates the same held keys, not freshly reopened substitutes.
+          def verify_unchanged!
+            checks = Thread.current[:ace_assign_control_checks]&.fetch(object_id, nil)
+            unavailable!("Lifecycle control is not held") unless checks && !checks.empty?
+            checks.each(&:call)
+            true
+          end
+
+          private
+
+          def with_locks(keys, mode, deadline: nil)
+            callback_error = nil
+            ordered = keys!(keys)
+            deadline!(deadline) if deadline
+            with_root do |handles, identities|
+              locks, markers, marker_facts, lock_facts = [], [], [], []
+              begin
+                ordered.each do |key|
+                  path, marker_path = paths(key)
+                  lock = @files.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+                  locks << lock
+                  validate_file!(path, lock, empty: true)
+                  lock_facts << file_metadata(lock.stat)
+                  unless lock.flock(mode | File::LOCK_NB)
+                    raise AttemptErrors::MaintenanceBusy, "Lifecycle control is under maintenance"
+                  end
+                  marker = @files.open(marker_path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+                  markers << marker
+                  live_marker!(key, marker_path, marker)
+                  marker_facts << file_metadata(marker.stat)
+                end
+                deadline!(deadline) if deadline
+                unchanged!(handles, identities)
+                check = proc do
+                  ordered.each_with_index do |key, index|
+                    path, marker_path = paths(key)
+                    lock, marker = locks.fetch(index), markers.fetch(index)
+                    validate_file!(path, lock, empty: true)
+                    unless file_metadata(lock.stat) == lock_facts.fetch(index) &&
+                        file_metadata(marker.stat) == marker_facts.fetch(index)
+                      unavailable!("Lifecycle control key changed")
+                    end
+                    marker.rewind
+                    live_marker!(key, marker_path, marker)
+                  end
+                  unchanged!(handles, identities)
+                end
+                registry = Thread.current[:ace_assign_control_checks] ||= {}
+                checks = registry[object_id] ||= []
+                checks << check
+                begin
+                  begin
+                    result = yield
+                  rescue Exception => error
+                    callback_error = error
+                    raise
+                  end
+                  verify_unchanged!
+                ensure
+                  checks.pop
+                  registry.delete(object_id) if checks.empty?
+                end
+                deadline!(deadline) if deadline
+                result
+              ensure
+                close_all!(locks + markers)
+              end
+            end
+          rescue SystemCallError, IOError, Ace::Runtime::RuntimeUnavailableError
+            raise if callback_error
+            unavailable!("Lifecycle control admission is unavailable")
+          end
+
+          def with_root
+            callback_error = nil
+            handles, identities = {}, {}
+            begin
+              parts = @root.split("/").reject(&:empty?)
+              (["/"] + parts.each_index.map { |index| "/" + parts.take(index + 1).join("/") }).each do |path|
+                handle = @files.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+                handles[path] = handle
+                unless handle.stat.directory? && file_identity(handle.stat) == file_identity(@files.lstat(path))
+                  unavailable!("Lifecycle control directory changed")
+                end
+                @protection.verify!(path, handle, directory: true)
+                identities[path] = file_identity(handle.stat)
+              end
+              root = handles.fetch(@root).stat
+              unless [root.uid, root.gid, root.mode & 0o7777] == [@uid, @gid, 0o700] &&
+                  (!@identity || [root.dev, root.ino, root.uid, root.gid] == @identity.values_at("device", "inode", "uid", "gid"))
+                unavailable!("Lifecycle control original root differs")
+              end
+              begin
+                result = yield handles, identities
+              rescue Exception => error
+                callback_error = error
+                raise
+              end
+              unchanged!(handles, identities)
+              result
+            ensure
+              close_all!(handles.values)
+            end
+          rescue SystemCallError, IOError, Ace::Runtime::RuntimeUnavailableError
+            raise if callback_error
+            unavailable!("Lifecycle control root is unavailable")
+          end
+
+          def unchanged!(handles, identities)
+            handles.each do |path, handle|
+              unless file_identity(handle.stat) == identities.fetch(path) &&
+                  identities.fetch(path) == file_identity(@files.lstat(path))
+                unavailable!("Lifecycle control directory changed")
+              end
+              @protection.verify!(path, handle, directory: true)
+            end
+          end
+
+          def create_or_open!(path, bytes, root)
+            created = true
+            file = begin
+              @files.open(path, File::RDWR | File::CREAT | File::EXCL | File::NOFOLLOW | File::NONBLOCK, 0o600)
+            rescue Errno::EEXIST
+              created = false
+              @files.open(path, File::RDONLY | File::NOFOLLOW | File::NONBLOCK)
+            end
+            if created
+              file.write(bytes)
+              file.flush
+              file.fsync
+              root.fsync
+            end
+            file.rewind
+            [file, created]
+          rescue Exception
+            file&.close
+            raise
+          end
+
+          def validate_file!(path, file, empty: false)
+            stat = file.stat
+            unless stat.file? && stat.nlink == 1 && [stat.uid, stat.gid, stat.mode & 0o7777] == [@uid, @gid, 0o600] &&
+                file_identity(stat) == file_identity(@files.lstat(path)) && (empty ? stat.size.zero? : stat.size.between?(1, 8192))
+              unavailable!("Lifecycle control file differs")
+            end
+            @protection.verify!(path, file, directory: false)
+          end
+
+          def live_marker!(key, path, file)
+            validate_file!(path, file)
+            before = file.stat
+            bytes = file.read(8193)
+            state = LifecycleExclusion.workspace_marker!(bytes: bytes, key: key)
+            unless bytes.bytesize == before.size && file_metadata(before) == file_metadata(file.stat) &&
+                file_metadata(before) == file_metadata(@files.lstat(path))
+              unavailable!("Lifecycle control marker changed")
+            end
+            raise AttemptErrors::Conflict, "Lifecycle control identity is fenced" if state.fetch("removed")
+          end
+
+          def keys!(keys)
+            values = Array(keys).uniq
+            unless values.any? && values.all? { |key| key.is_a?(String) && key.match?(/\A(?:task|assignment):[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/) }
+              unavailable!("Lifecycle control keys differ")
+            end
+            values.sort_by { |key| [key.start_with?("task:") ? 0 : 1, key] }
+          end
+
+          def key!(kind, id)
+            unavailable!("Lifecycle control key differs") unless id.is_a?(String) && token?(id)
+            "#{kind}:#{id}"
+          end
+          def token?(value) = value.match?(/\A[A-Za-z0-9][A-Za-z0-9._-]{0,127}\z/)
+          def paths(key)
+            stem = File.join(@root, Digest::SHA256.hexdigest(key))
+            [stem + ".lock", stem + ".state.json"]
+          end
+          def file_identity(stat) = [stat.dev, stat.ino, stat.uid, stat.gid, stat.mode]
+          def file_metadata(stat) = file_identity(stat) + [stat.size, stat.mtime, stat.ctime]
+          def unavailable!(message) = raise(AttemptErrors::EvidenceUnavailable, message)
+          def deadline!(deadline)
+            unless deadline.is_a?(Numeric) && deadline.finite? && deadline > Process.clock_gettime(Process::CLOCK_MONOTONIC)
+              raise AttemptErrors::MaintenanceBusy, "Lifecycle control admission deadline elapsed"
+            end
+          end
+          def close_all!(files)
+            error = nil
+            files.reverse_each do |file|
+              begin
+                file.close unless file.closed?
+              rescue SystemCallError, IOError => caught
+                error ||= caught
+              end
+            end
+            raise error if error
+          end
+        end
+      end
+    end
+  end
+end