ace-hitl-contract 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 898a6d72e810e38ec458ab4c6fed1ef44f7153fb4caa4385ccbfc90dcf32c6de
+  data.tar.gz: b31aebd8f351ae2bd240eee1a11a18532065bebfda87b005deefc66d49c59067
+SHA512:
+  metadata.gz: 77410b2ccb1fd4477c953a081165427e6ab587540df113cb2806314131c0e3577e17b7f32931c5983230c6021cd7b494169aea4ff93d3bf7fa52e7ec7af11379
+  data.tar.gz: ddb96c185b8e5c4a1ab74e0a5328131773f9dd2369deeecf0041bd6373ba884e177062c465a807143ad8594fd7c093006c3fdfa2386ba082038daf3f153e656f

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-04
+
+### Added
+
+- Extract the existing HITL provider references, results and error hierarchy into one dependency-free protocol package, preserving their namespace and behavior.

data/README.md

@@ -0,0 +1,14 @@
+# ace-hitl-contract
+
+Shared provider protocol for ACE HITL request orchestration and delivery adapters. It has no runtime gem dependencies and performs no service, assignment or transport initialization.
+
+```ruby
+require "ace/hitl/contract"
+
+ref = Ace::Hitl::Providers::Ref.from_env
+result = Ace::Hitl::Providers::DeliverResult.new(ref: ref, state: :delivered)
+```
+
+The protocol owns `Ref`, `AskResult`, `DeliverResult` and the provider error hierarchy under `Ace::Hitl::Providers`. Full registry and locked assignment authority remain in `ace-hitl`. Runtime adapters use this leaf package without loading the privileged HITL lifecycle.
+
+Run package tests from the ACE checkout with `bin/ace-test ace-hitl-contract all`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/lib/ace/hitl/contract/errors.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Providers
+      # Error model for HITL provider adapters (spec 8wm.t.vrz §2).
+      class Error < StandardError; end
+
+      # The provider name is not in the registry.
+      class UnknownProviderError < Error; end
+
+      # The reverse address (herdr session + pane) is absent or invalid.
+      # Ask fails closed before any event or transport state is created.
+      class InvalidRefError < Error; end
+
+      # The transport send failed (binary missing, non-zero exit,
+      # unparseable output) after the local event may already exist.
+      class ProviderUnavailableError < Error; end
+
+      # The provider does not implement the requested operation.
+      class UnsupportedOperationError < Error; end
+    end
+  end
+end

data/lib/ace/hitl/contract/ref.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Ace
+  module Hitl
+    module Providers
+      # Typed reverse address of the asking agent: herdr session + pane
+      # (spec 8wm.t.vrz §3). Versioned schema ace.hitl.ref/v1; captured
+      # fail-closed from the herdr environment at ask time. ace-herdr
+      # exports both variables when it bootstraps an agent pane.
+      #
+      # The ref identifies WHERE the answer goes; it never carries answer
+      # content.
+      class Ref
+        SCHEMA = "ace.hitl.ref/v1"
+        SESSION_ENV = "HERDR_SESSION"
+        PANE_ENV = "HERDR_PANE"
+        MAX_LENGTH = 128
+        TOKEN_PATTERN = /\A[A-Za-z0-9._:-]+\z/.freeze
+
+        attr_reader :session, :pane
+
+        def initialize(session:, pane:)
+          @session = session
+          @pane = pane
+        end
+
+        # Fail closed: raises InvalidRefError naming the offending variable
+        # and rule when the reverse address is absent or invalid.
+        def self.from_env(env = ENV)
+          session = validate!(env[SESSION_ENV], SESSION_ENV)
+          pane = validate!(env[PANE_ENV], PANE_ENV)
+          new(session: session, pane: pane)
+        end
+
+        def self.validate!(value, source)
+          token = value.to_s.strip
+          if token.empty?
+            raise InvalidRefError,
+              "#{source} is required (herdr reverse address, #{SCHEMA})"
+          end
+          if token.length > MAX_LENGTH
+            raise InvalidRefError,
+              "#{source} exceeds #{MAX_LENGTH} characters"
+          end
+          unless token.match?(TOKEN_PATTERN)
+            raise InvalidRefError,
+              "#{source} contains invalid characters " \
+              "(allowed: letters, digits, '.', '_', ':', '-')"
+          end
+
+          token
+        end
+
+        def to_h
+          {schema: SCHEMA, session: session, pane: pane}
+        end
+      end
+    end
+  end
+end

data/lib/ace/hitl/contract/results.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Providers
+      # ask(question:, ...) result: local event id + relay request id.
+      AskResult = Struct.new(:event_id, :request_id, keyword_init: true)
+
+      # deliver(ref, answer) result; state is :delivered, :retryable
+      # (safe to re-push identical content) or :failed.
+      DeliverResult = Struct.new(:ref, :state, keyword_init: true)
+    end
+  end
+end

data/lib/ace/hitl/contract/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Ace
+  module Hitl
+    module Contract
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/ace/hitl/contract.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "contract/version"
+require_relative "contract/errors"
+require_relative "contract/ref"
+require_relative "contract/results"

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: ace-hitl-contract
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michal Czyz
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ace-support-test-helpers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Pure HITL provider vocabulary shared by request orchestration and delivery
+  adapters, without activating assignment or privileged HITL service dependencies.
+email:
+- mc@cs3b.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- Rakefile
+- lib/ace/hitl/contract.rb
+- lib/ace/hitl/contract/errors.rb
+- lib/ace/hitl/contract/ref.rb
+- lib/ace/hitl/contract/results.rb
+- lib/ace/hitl/contract/version.rb
+homepage: https://github.com/cs3b/ace
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/cs3b/ace/tree/main/ace-hitl-contract/
+  changelog_uri: https://github.com/cs3b/ace/blob/main/ace-hitl-contract/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Shared HITL provider reference, result and error protocol
+test_files: []