ace-hitl-contract 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb90db31c845024c2415ceab4ad473bfd6843323cc5d9a6e6c3a4df6f822e7e3
-  data.tar.gz: 267b6eb9266824a22151ce5c5a38b260d4f384424090ba07148afc1bf34c063f
+  metadata.gz: 688f70e592148bdab2e4e948f65d8d181874991857eef5ece11cb21efacd2d5c
+  data.tar.gz: bbde12cb9d41744dc25e876697ffd94002105db82f0e2f912e7f4d5ee55fc144
 SHA512:
-  metadata.gz: 1539a233ebf5dd1eda0b6efc2aee3958d934d61d50b4bb4f1ba4e7911d6fedde8dde7fce9e48fa96621b4ac142ba72be1471d8b9d5c46e3477c45a68ac5e3db1
-  data.tar.gz: 2ac3d16e9465cd971f258767f43252255cc2de2e8564a115d56743c7efd59d00e918d3023430e68a8ad03a8c8c9811717dc52cea78a94fa562555781040cf85a
+  metadata.gz: c2984a72c8276b92e8a1961b95a9cd8f4de8b9dba18d4c7255cbbe7e64a16e26ac303be61c67186bd77f0d5a748b278b0e9773077bcb6eb68c0b4019378503fb
+  data.tar.gz: 66decc3f22461f6caf6eb6ee07f2646ab0ba12c46fb9505b33dc0b230811eb099d56eae4f2b3a35b6deec7193053630386c4a521ce94da6073b09a15eee2a7c0

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-16
+
+### Added
+
+- Add a closed operator-question envelope and tagged request union without assignment/attempt claims; ship its schema and example. Keep managed request validation unchanged.
+
+### Changed
+
+- Include exact project identity in shared ingress checkpoint examples for project-scoped proposal authorization.
+
 ## [0.2.1] - 2026-10-10
 
 ### Fixed

data/README.md

@@ -53,3 +53,16 @@ configuration `environment.overrides.ACE_HITL_SCHEMA_PYTHON`; run the absolute
 test file with `bin/ace-test ace-hitl-contract ... --config-path /absolute/fixture.yml`.
 The default package run skips this external validator check; no runtime gem
 dependency or production configuration is added.
+
+`RequestEnvelope.load` is the closed union of the unchanged managed schema and
+`OperatorEnvelope` (`ace.hitl.operator-question/v1`). The operator variant fixes
+`context: operator-question` and `kind: question`, names the real requester UID,
+project, immutable incarnation/correlation and nonsecret question/input digests.
+It rejects assignment, attempt, reverse, effects, OTP and publication fields.
+`RequestEnvelope.from_facts` also checks the owner's exact attribution, project,
+classification and question payload binding. Its operator schema and example
+ship as `operator-question.v1.schema.json` and `examples/operator-question.json`.
+Structural validation grants no identity or execution authority; generic HITL
+checks the kernel principal and installed grants. A future command context needs
+its own canonical provenance and validator; an operator question cannot stand in
+for command execution or publisher OTP.

data/lib/ace/hitl/contract/examples/ingress-checkpoints.json

@@ -9,7 +9,8 @@
       "healthy": false,
       "drained": false,
       "checkpoint": null,
-      "unresolved": []
+      "unresolved": [],
+      "project": "ace"
     },
     {
       "schema": "ace.hitl.hermes.ingress-checkpoint/v1",
@@ -23,7 +24,8 @@
         "through": "2026-10-05T10:00:00Z",
         "sequence": 4
       },
-      "unresolved": []
+      "unresolved": [],
+      "project": "ace"
     },
     {
       "schema": "ace.hitl.hermes.ingress-checkpoint/v1",
@@ -42,9 +44,11 @@
           "request": "hitl-abcdef1234",
           "revision": "def456",
           "received_at": "2026-10-05T09:59:59Z",
-          "status": "unresolved"
+          "status": "unresolved",
+          "project": "ace"
         }
-      ]
+      ],
+      "project": "ace"
     }
   ]
 }

data/lib/ace/hitl/contract/examples/operator-question.json

@@ -0,0 +1,13 @@
+{
+  "schema": "ace.hitl.operator-question/v1",
+  "context": "operator-question",
+  "request_id": "operator-abcdef",
+  "request_incarnation": "0123456789abcdef",
+  "project": "lab-config",
+  "requester": "mo",
+  "requester_uid": 1000,
+  "correlation_id": "operator-abcdef",
+  "kind": "question",
+  "payload_sha256": "0cd45088a48787af9eb875a2de1912f5146371da61e69f44f1843ff7a8eb0cb9",
+  "input_sha256": "daad7a6851f6289cae1d2f2088629fd9d00133ad517f0e6ef697c2f36b8dc62d"
+}

data/lib/ace/hitl/contract/operator-question.v1.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ace.tools/schemas/hitl/operator-question.v1.schema.json",
+  "title": "Unassigned operator question; structure is not authority",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema",
+    "context",
+    "request_id",
+    "project",
+    "requester",
+    "correlation_id",
+    "request_incarnation",
+    "requester_uid",
+    "kind",
+    "payload_sha256",
+    "input_sha256"
+  ],
+  "properties": {
+    "schema": {
+      "const": "ace.hitl.operator-question/v1"
+    },
+    "context": {
+      "const": "operator-question"
+    },
+    "request_id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "project": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "requester": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "correlation_id": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
+    },
+    "request_incarnation": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{16}$"
+    },
+    "requester_uid": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "kind": {
+      "const": "question"
+    },
+    "payload_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "input_sha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    }
+  }
+}

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+require "json"
+require_relative "managed_envelope"
+
+module Ace
+  module Hitl
+    module Contract
+      # A question has a real local requester and project, but no execution or
+      # effect authority. Its closed schema cannot carry managed/OTP grants.
+      class OperatorEnvelope
+        SCHEMA = "ace.hitl.operator-question/v1"
+        FIELDS = %w[schema context request_id request_incarnation project requester requester_uid
+          correlation_id kind payload_sha256 input_sha256].freeze
+
+        def self.load(value, expected: {})
+          data = value.is_a?(String) ? JSON.parse(value) : JSON.parse(JSON.generate(value))
+          unless data.is_a?(Hash) && data.keys.sort == FIELDS.sort && data["schema"] == SCHEMA &&
+              data["context"] == "operator-question" && data["kind"] == "question"
+            raise InvalidEnvelope, "invalid closed operator question envelope"
+          end
+          %w[request_id project requester correlation_id].each do |key|
+            unless data[key].is_a?(String) && ManagedEnvelope::TOKEN.match?(data[key])
+              raise InvalidEnvelope, "invalid operator #{key}"
+            end
+          end
+          unless data["request_incarnation"].is_a?(String) && data["request_incarnation"].match?(/\A[0-9a-f]{16}\z/) &&
+              data["requester_uid"].is_a?(Integer) && data["requester_uid"] >= 0 &&
+              data["correlation_id"] == data["request_id"] &&
+              %w[payload_sha256 input_sha256].all? { |key|
+                data[key].is_a?(String) && ManagedEnvelope::DIGEST.match?(data[key]) }
+            raise InvalidEnvelope, "invalid operator question identity or input digest"
+          end
+          expected.each do |key, wanted|
+            raise InvalidEnvelope, "operator #{key} differs from authoritative binding" unless data[key.to_s] == wanted
+          end
+          data
+        rescue JSON::ParserError, JSON::GeneratorError, TypeError => e
+          raise InvalidEnvelope, "invalid operator envelope JSON (#{e.class})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+require_relative "operator_envelope"
+
+module Ace
+  module Hitl
+    module Contract
+      # Explicit tagged union; unknown schemas never become an operator context.
+      module RequestEnvelope
+        VALIDATORS = {ManagedEnvelope::SCHEMA => ManagedEnvelope, OperatorEnvelope::SCHEMA => OperatorEnvelope}.freeze
+        module_function
+        def load(value, expected: {})
+          data = value.is_a?(String) ? JSON.parse(value) : value
+          validator = data.is_a?(Hash) && VALIDATORS[data["schema"]]
+          raise InvalidEnvelope, "unsupported request context schema" unless validator
+          validator.load(data, expected: expected)
+        rescue JSON::ParserError
+          raise InvalidEnvelope, "invalid request context JSON"
+        end
+
+        def from_facts(facts)
+          envelope = load(facts.fetch("envelope"))
+          expected = {request_id: facts["id"], correlation_id: facts["id"], project: facts["project"],
+            requester: facts["requester"], kind: facts["kind"]}
+          if envelope["schema"] == ManagedEnvelope::SCHEMA
+            expected.merge!(assignment_id: facts["assignment"], attempt_id: facts["attempt"])
+          else
+            expected[:requester_uid] = facts["requester_uid"]
+            if facts.key?("question") && (!facts["question"].is_a?(String) ||
+                Digest::SHA256.hexdigest(facts["question"]) != envelope.fetch("payload_sha256"))
+              raise InvalidEnvelope, "operator question payload differs from its binding"
+            end
+            unless facts["sensitive"] == false && !facts["effect"] && !facts["otp"] &&
+                !facts["assignment"] && !facts["attempt"] && !facts["publication_binding"]
+              raise InvalidEnvelope, "operator question facts cannot claim managed or secret authority"
+            end
+          end
+          load(envelope, expected: expected)
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Ace
   module Hitl
     module Contract
-      VERSION = "0.2.1"
+      VERSION = "0.3.0"
     end
   end
 end

data/lib/ace/hitl/contract.rb

@@ -5,3 +5,5 @@ require_relative "contract/errors"
 require_relative "contract/ref"
 require_relative "contract/results"
 require_relative "contract/managed_envelope"
+
+require_relative "contract/request_envelope"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ace-hitl-contract
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Michal Czyz
@@ -68,9 +68,13 @@ files:
 - lib/ace/hitl/contract/examples/managed-answer.json
 - lib/ace/hitl/contract/examples/managed-otp-request.json
 - lib/ace/hitl/contract/examples/managed-request.json
+- lib/ace/hitl/contract/examples/operator-question.json
 - lib/ace/hitl/contract/managed.v1.schema.json
 - lib/ace/hitl/contract/managed_envelope.rb
+- lib/ace/hitl/contract/operator-question.v1.schema.json
+- lib/ace/hitl/contract/operator_envelope.rb
 - lib/ace/hitl/contract/ref.rb
+- lib/ace/hitl/contract/request_envelope.rb
 - lib/ace/hitl/contract/results.rb
 - lib/ace/hitl/contract/secret_gate.rb
 - lib/ace/hitl/contract/version.rb