ace-lab 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54eee52265f20d22376fcdf7ac0a748be0c8ec5d7400259310a1a5a37d2f373e
-  data.tar.gz: e9b3746081e8790a2764f8dcbbd54650ddb3a23890cdb653c689c5a5d6ad7d5c
+  metadata.gz: c6487b764fe853b0272a43afa43fd2e6819669c6dc3593022ab55946925b2a2e
+  data.tar.gz: c588bd4bc130eff246e02546b40a11fa9ed06e8c575560d292a291c5d2d1665e
 SHA512:
-  metadata.gz: 78d706d9b60416afdd98a12bbf98dfe90a12e2cd4105c29f3bab5b177dcdea70f8ac0753e35926107790afbdd1fc03c9e792b9c4fd85a45b1dac716122032060
-  data.tar.gz: 646f3f2fae98bc011fabf589a1175c6248f36cd4cd89a7dc2172e0010287affbb16bebe4dc33ce8af5b53e263d2743d1af7c4410c2a307c0e08b215a57aad18f
+  metadata.gz: 3c6974042b3ac8cc638d3782b3d2e4c4be19de2de5860cc6c91e3d020cdc0338e7cb187d932ae64353f7994304b3b0f284533cef21b6919233e313a7af1bea6a
+  data.tar.gz: 2e6908502fdd3870f7403e7d6f56b07d1b5edb07acbdc6591135aae8a0227ae85ab8724c7e079e4a1d91bbf61a53277d0a84e38c23be958e540c1b9c7d8306ae

data/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.2.0] - 2026-10-02
+
+### Added
+
+- `service request` and `service status` for exact authorized operations,
+  idempotent assignment-journal claims, peer-verified execution receipts,
+  dry-run previews, and conservative uncertain-state recovery.
+
+### Fixed
+
+- Recheck the configured operation, authorization, and lease at dispatch;
+  bind terminal receipts to the assignment request before acceptance.
+
 ## [0.1.0] - 2026-09-28
 
 ### Added

data/README.md

@@ -1,12 +1,14 @@
 ## ace-lab
 
-Topology and routing CLI for the Lab: address projects, agents, and services
-by stable IDs. Part of ACE (Agentic Coding Environment).
+Topology, routing, and scoped service request CLI for the Lab. Part of ACE
+(Agentic Coding Environment).
 
 `ace-lab` answers one question -- *what is the stable ID of the project, agent,
 or service I mean, and what is it authorized and able to do?* -- from
-configuration alone. It never invokes Lab, never reads credentials, tracks no
-work, and never guesses transient pane or session identifiers.
+configuration. Topology queries never invoke a service. The `service`
+commands submit configured operations through a verified executor and use
+`ace-assign` for durable request evidence. No command hands credentials to
+the caller or guesses transient pane or session identifiers.
 
 ### Install
 
@@ -17,12 +19,12 @@ work, and never guesses transient pane or session identifiers.
 Configure topology via the ADR-022 cascade (`~/.ace/lab/config.yml` or
 `.ace/lab/config.yml`; deployed values are owned by the `lab-config`
 repository). Authorization grants live in a separate deployment-controlled
-file at the fixed path `/etc/lab/ace-lab/authorization.yml` — root-owned and
-not group/world-writable, verified at every query — never in the
+file at the fixed path `/etc/lab/ace-lab/authorization.yml` -- root-owned and
+not group/world-writable, verified at every query -- never in the
 caller-writable cascade and never at a caller-selected location:
 
 ```yaml
-# .ace/lab/config.yml — topology only
+# .ace/lab/config.yml -- topology only
 schema_version: 1
 topology:
   projects:
@@ -56,6 +58,17 @@ Query it:
     ace-lab resolve --id atlas-planner --format json
     ace-lab route --project atlas --capability search --format json
 
+Request a configured operation for an active, managed assignment attempt:
+
+    ace-lab service request --project atlas --assignment A --attempt ATT \
+      --operation publish --input release.json --authorization DECISION \
+      --request-id REQUEST --dry-run
+    ace-lab service status --request REQUEST --format json
+
+The trusted grants file may also contain exact `operations` and
+`authorizations` mappings. See [usage](docs/usage.md) for the request schema,
+executor transport, and uncertain-state recovery.
+
 Every command prints one deterministic JSON document:
 
     {"status":"ok","data":{"entry":{"id":"atlas-search","project":"atlas",
@@ -92,19 +105,18 @@ Failures are classified: `missing`, `ambiguous`, `stale`, `unauthorized`,
   are `missing`; several equal candidates need a configured `default_for`, or
   the result is `ambiguous`. Another project's service is never picked.
 
-- **Read-only by contract.** No Lab invocation, no execution state, no
+- **Execution evidence is separate from topology.** `ace-lab service` uses a
 
-  scheduling, no credentials -- service invocation and execution state belong
-  to separate tools.
+  managed `ace-assign` attempt and its evidence ref. A lost executor receipt
+  remains uncertain and a repeated request ID never replays the effect.
 
 ### Non-goals
 
-`ace-lab` is not an execution-state engine. It does not invoke services
-(`8wr.t.qjx` owns the service contract), track Works or assignment state, or
-schedule anything. Deployed topology values are owned by `lab-config`
+`ace-lab` does not track Works or schedule anything. `ace-assign` owns attempt
+state; deployed operation handlers and topology values are owned by `lab-config`
 (`8wl.t.gad`); this package defines and validates the schema.
 
 ### Development
 
     bundle install
-    ace-test ace-lab        # or: bundle exec rake test from ace-lab/
+    bin/ace-test ace-lab all

data/docs/usage.md

@@ -1,13 +1,14 @@
 # ace-lab usage
 
-Topology and routing CLI for the Lab. Resolves stable project, agent, and
-service IDs from configuration -- without knowing transient pane IDs or
-holding service credentials.
+Topology, routing, and scoped service requests for the Lab. Resolves stable
+project, agent, and service IDs without transient pane IDs or shared service
+credentials.
 
 ## Commands
 
-All commands accept `--format json` (the only supported format; anything else
-is rejected) and `-q/--quiet` (suppress stdout; exit semantics unchanged).
+Topology commands accept `--format json` (the only supported format) and
+`-q/--quiet`. Service status accepts `--format json`; service request always
+emits JSON.
 
 ### `ace-lab projects`
 
@@ -58,6 +59,68 @@ Select a configured capable service in the requested project.
 
 Routing never invokes the service and never grants credentials.
 
+### `ace-lab service request`
+
+**Goal:** Ask a configured service to perform one named operation for an
+active, task-attached assignment attempt. First create a JSON input file:
+
+```json
+{"target":{"resource":"release/1.2.3","artifact_digest":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"},"arguments":{"version":"1.2.3"}}
+```
+
+Run a preview, then submit the exact request:
+
+```sh
+ace-lab service request --project atlas --assignment A --attempt ATT \
+  --operation publish --input release.json --authorization DECISION \
+  --request-id REQUEST --dry-run
+ace-lab service request --project atlas --assignment A --attempt ATT \
+  --operation publish --input release.json --authorization DECISION \
+  --request-id REQUEST
+```
+
+The preview reports `outcome: accepted` with `dry_run: true` and the selected
+service ID, target, and candidate head. It creates no request claim or effect.
+The second command returns `succeeded`, `failed`, or `uncertain` with a
+non-secret receipt when the executor confirms an outcome. A missing response
+leaves `uncertain` in the assignment evidence ref; do not retry with a new ID
+until the external outcome is reconciled. Repeating the same ID and input
+returns its stored state without dispatching again. A changed binding under
+the same ID is a `conflict` error.
+
+Input must be a JSON object of at most 64 KiB. `target.resource` is a stable
+resource ID; `target.artifact_digest`, when supplied, is a SHA-256 hex digest.
+Credential, password, secret, token, private-key, authorization, and env keys
+are rejected recursively. Operation arguments remain structured JSON sent to
+the executor; no caller-provided shell command or argv is accepted.
+
+| Option | Purpose |
+|--------|---------|
+| `--project` | Project stable ID |
+| `--assignment` | Assignment ID |
+| `--attempt` | Active managed attempt ID |
+| `--operation` | Configured named operation |
+| `--input` | Structured JSON file |
+| `--authorization` | Exact decision or configured automation reference |
+| `--request-id` | Idempotency key; use the same ID for retries/status |
+| `--dry-run` | Validate and show scope without an effect |
+
+### `ace-lab service status`
+
+```sh
+ace-lab service status --request REQUEST --format json
+```
+
+Expected output after a lost executor receipt:
+
+```json
+{"status":"ok","data":{"request_id":"REQUEST","outcome":"uncertain","state":"uncertain"}}
+```
+
+Only the original OS caller identity with project visibility can read the
+request. The authoritative state survives loss of the local assignment cache
+because it lives in the separate assignment evidence Git ref.
+
 ## Error semantics
 
 Errors are one deterministic JSON document on stdout plus a non-zero exit.
@@ -69,6 +132,10 @@ Errors are one deterministic JSON document on stdout plus a non-zero exit.
 | `stale` | Binding is inactive, unattested, or the instance identity was replaced |
 | `unauthorized` | Caller's verified local identity has no principal for the project |
 | `invalid_configuration` | Topology config violates the schema; message is actionable |
+| `invalid_input` | Service input or request ID is malformed |
+| `invalid_attempt` | Assignment attempt is absent, unmanaged, terminal, or has a stale candidate head |
+| `conflict` | Request ID is already bound to different input or scope |
+| `evidence_unavailable` | Assignment evidence ref cannot be written or read |
 
 Example:
 
@@ -115,7 +182,7 @@ Grants never live in the cascade: project and user documents are
 caller-writable, so an `authorization` section there is rejected as
 `invalid_configuration`. Grants come from a single deployment-controlled
 file at the **fixed path** `/etc/lab/ace-lab/authorization.yml` (installed
-by the `lab-config` deployment). The location is not caller-selectable —
+by the `lab-config` deployment). The location is not caller-selectable --
 there is no flag or environment override. At every query the tool verifies
 the file and every directory on its real path are root-owned and not
 group/world-writable, and opens the file `O_NOFOLLOW`; any failed
@@ -130,12 +197,51 @@ principals:
 The grants file is machine-global: it is validated structurally only, so a
 principal may reference projects absent from the current directory's
 topology. Such grants are valid but never match a locally configured
-project. All-digit principal keys are matched as uids only — an all-digit
+project. All-digit principal keys are matched as uids only -- an all-digit
 passwd username is authorized solely through its uid, so it can never
 consume a different account's numeric-uid grant.
 
 A missing trusted file means nobody is authorized (fail closed).
 
+### Trusted service policy
+
+The same deployment-owned file may contain `operations` and
+`authorizations`. An operation names one exact project and stable service ID,
+an executor OS UID, a valid lease, and either a fixed local argv or an absolute
+Unix socket path. The domain deployment owns actual handlers and credentials.
+The Unix service must authenticate the client's OS peer identity, validate
+the exact authorization and current lease itself, and return a structured
+receipt; ACE verifies the service peer UID before accepting that response.
+
+```yaml
+operations:
+  forge-sync:
+    project: atlas
+    service_id: atlas-sync
+    transport: unix
+    socket_path: /run/lab/atlas-sync.sock
+    executor_uid: 997
+    lease_expires_at: '2026-10-02T16:00:00Z'
+authorizations:
+  DECISION:
+    operation: forge-sync
+    project_id: atlas
+    assignment_id: A
+    attempt_id: ATT
+    input_digest: <sha256-of-canonical-json>
+    target: { resource: forge/repository, artifact_digest: null }
+    candidate_head: <exact-git-head>
+    caller_uid: 1000
+    expires_at: '2026-10-02T16:00:00Z'
+```
+
+The decision must match every listed field exactly and remain valid. A
+decision never supplies missing executor capability or credentials. For
+authenticated host maintenance, the policy also identifies an executable and
+evidence sink outside the deployment being replaced; its domain handler must
+enforce quiescence for all other product work. Environment `review-approval`
+is a named operation and never substitutes for an independent code review.
+
 Validation of the topology cascade rejects duplicate IDs (globally unique
 across projects, agents, services), unknown project references, malformed
 capabilities, defaults for undeclared capabilities, unusable endpoints
@@ -146,7 +252,7 @@ unknown projects.
 **Error messages are value-free by design:** validation runs before
 authorization, so messages use positional field locations
 (`topology.agents[0].project references an unknown project`) and never echo
-configured IDs, project names, or principal names — configuration defects
+configured IDs, project names, or principal names -- configuration defects
 cannot disclose topology to unauthorized callers.
 
 **Ownership:** deployed topology and authorization values are maintained by
@@ -172,7 +278,7 @@ reads; it never provisions.
   classify it `stale` -- an explicit unavailable result, never a routeable
   answer.
 
-- No Works, assignment state, or scheduling. Service invocation belongs to
+- No Works or scheduling. Service request claims and receipts use
 
-  `8wr.t.qjx`; execution state to `8wr.t.qjl`. The Lab execution binary
+  `ace-assign`'s evidence journal. The Lab execution binary
   (`/usr/local/bin/lab`) is never invoked or required.

data/lib/ace/lab/atoms/service_input.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module Ace
+  module Lab
+    module Atoms
+      # Bounded structured input for a named service operation. Only the
+      # digest enters the request index; input values never enter the journal.
+      module ServiceInput
+        MAX_BYTES = 64 * 1024
+        FORBIDDEN_KEYS = /credential|password|secret|token|private.key|authorization|\Aenv\z/i
+        SHA256 = /\A[0-9a-f]{64}\z/
+        RESOURCE = /\A[a-zA-Z0-9_.:\/-]{1,256}\z/
+
+        def self.load(path)
+          raise ArgumentError, "input file is missing" unless File.file?(path)
+          raise ArgumentError, "input exceeds #{MAX_BYTES} bytes" if File.size(path) > MAX_BYTES
+          data = JSON.parse(File.read(path))
+          raise ArgumentError, "input must be a JSON object" unless data.is_a?(Hash)
+          validate!(data)
+          data
+        rescue JSON::ParserError
+          raise ArgumentError, "input must be valid JSON"
+        end
+
+        def self.digest(data)
+          Digest::SHA256.hexdigest(JSON.generate(canonical(data)))
+        end
+
+        def self.target(data)
+          target = data["target"]
+          raise ArgumentError, "input.target must be an object" unless target.is_a?(Hash)
+          resource = target["resource"]
+          artifact = target["artifact_digest"]
+          raise ArgumentError, "input.target.resource must be a stable resource ID" unless
+            resource.is_a?(String) && resource.match?(RESOURCE)
+          if artifact && (!artifact.is_a?(String) || !artifact.match?(SHA256))
+            raise ArgumentError, "input.target.artifact_digest must be SHA-256"
+          end
+          {"resource" => resource, "artifact_digest" => artifact}
+        end
+
+        def self.canonical(value)
+          case value
+          when Hash then value.keys.sort.each_with_object({}) { |key, result| result[key] = canonical(value[key]) }
+          when Array then value.map { |item| canonical(item) }
+          else value
+          end
+        end
+
+        def self.validate!(value, depth = 0)
+          raise ArgumentError, "input nesting is too deep" if depth > 16
+          case value
+          when Hash
+            value.each do |key, item|
+              raise ArgumentError, "input has a forbidden field" if !key.is_a?(String) || key.match?(FORBIDDEN_KEYS)
+              validate!(item, depth + 1)
+            end
+          when Array then value.each { |item| validate!(item, depth + 1) }
+          when String, Integer, Float, TrueClass, FalseClass, NilClass
+            raise ArgumentError, "input contains a non-finite number" if value.is_a?(Float) && !value.finite?
+          else
+            raise ArgumentError, "input contains an unsupported value"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/service.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require_relative "support"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        module Service
+          module Output
+            def service
+              @service ||= Organisms::ServiceRequestService.new
+            end
+
+            def emit(envelope)
+              puts JSON.generate(envelope)
+              return if envelope["status"] == "ok"
+              error = envelope.fetch("error")
+              code = error.fetch("code")
+              message = error.fetch("message")
+              raise Ace::Support::Cli::Error, "#{code}: #{message}"
+            end
+          end
+
+          class Request < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Runtime
+            include Output
+
+            desc "Request one authorized, configured service operation"
+            option :project, type: :string, required: true, desc: "Project stable ID"
+            option :assignment, type: :string, required: true, desc: "Assignment ID"
+            option :attempt, type: :string, required: true, desc: "Managed attempt ID"
+            option :operation, type: :string, required: true, desc: "Named operation"
+            option :input, type: :string, required: true, desc: "Structured JSON input file"
+            option :authorization, type: :string, required: true, desc: "Exact authorization reference"
+            option :request_id, type: :string, required: true, desc: "Idempotency key"
+            option :dry_run, type: :boolean, desc: "Validate without claiming or executing"
+
+            def call(project:, assignment:, attempt:, operation:, input:, authorization:, request_id:, **options)
+              reject_identity_flags!(options)
+              emit(service.request(project: project, assignment: assignment, attempt: attempt,
+                operation: operation, input_path: input, authorization: authorization,
+                request_id: request_id, dry_run: options[:dry_run]))
+            end
+          end
+
+          class Status < Ace::Support::Cli::Command
+            include Ace::Support::Cli::Base
+            include Runtime
+            include Output
+
+            desc "Read the authoritative outcome of a service request"
+            option :request, type: :string, required: true, desc: "Request ID"
+            option :format, type: :string, desc: "Output format (json only)"
+
+            def call(request:, **options)
+              ensure_json_format!(options)
+              emit(service.status(request_id: request))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli.rb

@@ -8,6 +8,7 @@ require_relative "cli/commands/agents"
 require_relative "cli/commands/services"
 require_relative "cli/commands/resolve"
 require_relative "cli/commands/route"
+require_relative "cli/commands/service"
 
 module Ace
   module Lab
@@ -23,7 +24,9 @@ module Ace
         ["agents", "List lab agents in a project by stable ID"],
         ["services", "List lab services in a project by stable ID"],
         ["resolve", "Resolve one lab entry by exact stable ID"],
-        ["route", "Select a configured capable service in a project"]
+        ["route", "Select a configured capable service in a project"],
+        ["service request", "Request one authorized service operation"],
+        ["service status", "Read a service request outcome"]
       ].freeze
 
       HELP_EXAMPLES = [
@@ -47,6 +50,8 @@ module Ace
       register "services", CLI::Commands::Services.new
       register "resolve", CLI::Commands::Resolve.new
       register "route", CLI::Commands::Route.new
+      register "service request", CLI::Commands::Service::Request.new
+      register "service status", CLI::Commands::Service::Status.new
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

data/lib/ace/lab/models/service_receipt.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Models
+      # Non-secret result submitted to the assignment evidence coordinator.
+      # The coordinator independently verifies every binding before acceptance.
+      module ServiceReceipt
+        BINDING_FIELDS = %w[request_id assignment_id attempt_id project_id operation
+          input_digest target candidate_head].freeze
+
+        def self.build(binding, executor_result)
+          BINDING_FIELDS.to_h { |field| [field, binding.fetch(field)] }.merge(executor_result)
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/grant_resolver.rb

@@ -23,6 +23,22 @@ module Ace
         MAX_SYMLINK_HOPS = 8
 
         class << self
+          # Read the full deployment-owned policy for service execution.
+          # Topology remains a routing hint; it never supplies authority.
+          def trusted_document(path)
+            content = read_verified(path)
+            return {} if content.nil?
+            document = YAML.safe_load(content, permitted_classes: [Date], aliases: true)
+            unless document.is_a?(Hash)
+              raise Ace::Lab::InvalidConfigurationError,
+                "invalid lab configuration: trusted authorization file must contain a mapping"
+            end
+            document
+          rescue Psych::Exception
+            raise Ace::Lab::InvalidConfigurationError,
+              "invalid lab configuration: trusted authorization file could not be parsed"
+          end
+
           # @param documents [Array<Hash>] {path:, document:, defaults:}
           #   from Ace::Lab.cascade_documents
           # @param topology [Hash] normalized topology (project IDs)

data/lib/ace/lab/molecules/service_executor.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "socket"
+require "timeout"
+require "time"
+
+module Ace
+  module Lab
+    module Molecules
+      # Executes one fixed, deployment-configured argv under its OS account.
+      # Domain handlers receive structured JSON on stdin and return a small
+      # receipt; their stdout/stderr are never journaled or returned to callers.
+      class ServiceExecutor
+        def execute(operation:, request:, input:, policy:, authorization:)
+          current = policy.operation!(request.fetch("operation"), project: request.fetch("project_id"),
+            service_id: request.fetch("service_id"))
+          raise SecurityError, "executor operation changed before dispatch" unless current == operation
+          policy.authorize!(authorization, request)
+          if Time.iso8601(operation.fetch("lease_expires_at")) <= Time.now.utc
+            raise SecurityError, "executor lease has expired"
+          end
+          out = if operation.fetch("transport", "local") == "unix"
+            invoke_unix(operation, request, input)
+          else
+            invoke_local(operation, request, input)
+          end
+          return nil unless out && out.bytesize <= 16 * 1024
+          response = JSON.parse(out)
+          return nil unless valid_response?(response, request)
+          {"outcome" => response.fetch("outcome"), "evidence" => response.fetch("evidence"),
+           "executor_uid" => operation.fetch("executor_uid")}
+        rescue JSON::ParserError, Errno::ENOENT, Errno::EACCES, Errno::ECONNREFUSED, EOFError, Timeout::Error
+          nil
+        end
+
+        private
+
+        def invoke_local(operation, request, input)
+          unless Process.uid == operation.fetch("executor_uid") && Process.euid == operation.fetch("executor_uid")
+            raise SecurityError, "current OS identity is not the configured executor"
+          end
+          out, _stderr, status = Timeout.timeout(30) do
+            Open3.capture3(*operation.fetch("argv"),
+              stdin_data: JSON.generate({"request" => request, "input" => input}))
+          end
+          status.success? ? out : nil
+        end
+
+        def invoke_unix(operation, request, input)
+          path = operation.fetch("socket_path")
+          stat = File.lstat(path)
+          unless stat.socket? && stat.uid == operation.fetch("executor_uid") && (stat.mode & 0o002).zero?
+            raise SecurityError, "service socket owner or permissions do not match the executor"
+          end
+          UNIXSocket.open(path) do |socket|
+            peer_uid, = socket.getpeereid
+            raise SecurityError, "service peer identity does not match the executor" unless peer_uid == stat.uid
+            socket.write(JSON.generate({"request" => request, "input" => input}) + "\n")
+            socket.flush
+            Timeout.timeout(30) { socket.gets(16 * 1024 + 1) }
+          end
+        end
+
+        def valid_response?(response, request)
+          response.is_a?(Hash) && response.keys.sort == %w[evidence input_digest outcome request_id] &&
+            response["request_id"] == request["request_id"] &&
+            response["input_digest"] == request["input_digest"] &&
+            %w[succeeded failed].include?(response["outcome"]) &&
+            response["evidence"].is_a?(Array) && !response["evidence"].empty? &&
+            response["evidence"].all? do |item|
+              item.is_a?(Hash) && item.keys.sort == %w[ref sha256] &&
+                item["ref"].is_a?(String) && item["ref"].match?(/\A[a-zA-Z0-9_.:\/-]{1,256}\z/) &&
+                item["sha256"].is_a?(String) && item["sha256"].match?(/\A[0-9a-f]{64}\z/)
+            end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/molecules/service_policy.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Ace
+  module Lab
+    module Molecules
+      # Deployment-owned operation and authorization facts. The caller may
+      # name a reference but cannot define its scope or executor binding.
+      class ServicePolicy
+        NAME = /\A[a-z][a-z0-9-]{0,63}\z/
+        ID = /\A[a-zA-Z0-9][a-zA-Z0-9_.-]{0,127}\z/
+
+        def initialize(document)
+          @operations = document.fetch("operations", {})
+          @authorizations = document.fetch("authorizations", {})
+          unless @operations.is_a?(Hash) && @authorizations.is_a?(Hash)
+            raise Ace::Lab::InvalidConfigurationError, "trusted service policy must contain mappings"
+          end
+        end
+
+        def operation!(name, project:, service_id:)
+          raise ArgumentError, "invalid operation name" unless name.to_s.match?(NAME)
+          operation = @operations[name]
+          raise SecurityError, "operation is not configured" unless operation.is_a?(Hash)
+          unless operation["project"] == project && operation["service_id"] == service_id
+            raise SecurityError, "operation does not authorize the selected service in this project"
+          end
+          transport = operation.fetch("transport", "local")
+          unless %w[local unix].include?(transport)
+            raise Ace::Lab::InvalidConfigurationError, "configured service transport is invalid"
+          end
+          if transport == "local"
+            argv = operation["argv"]
+            unless argv.is_a?(Array) && !argv.empty? && argv.all? { |v| v.is_a?(String) && !v.empty? } &&
+                argv.first.start_with?("/") && File.file?(argv.first) && File.executable?(argv.first)
+              raise Ace::Lab::InvalidConfigurationError, "configured operation needs a fixed executable argv"
+            end
+          elsif !operation["socket_path"].is_a?(String) || !operation["socket_path"].start_with?("/")
+            raise Ace::Lab::InvalidConfigurationError, "unix service needs an absolute socket path"
+          end
+          uid = operation["executor_uid"]
+          raise Ace::Lab::InvalidConfigurationError, "configured executor UID is invalid" unless uid.is_a?(Integer) && uid >= 0
+          validate_executable!(operation["argv"].first, uid) if transport == "local"
+          expires_at = parse_time(operation["lease_expires_at"])
+          raise SecurityError, "executor lease has expired" if expires_at <= Time.now.utc
+          if operation["host_maintenance"] == true
+            deployment = operation["deployment_root"].to_s
+            sink = operation["evidence_sink"].to_s
+            executable = operation.dig("argv", 0).to_s
+            unless deployment.start_with?("/") && sink.start_with?("/") && executable.start_with?("/") &&
+                !inside?(executable, deployment) && !inside?(sink, deployment)
+              raise Ace::Lab::InvalidConfigurationError,
+                "host maintenance needs executable and evidence sink outside the replaced deployment"
+            end
+            validate_executable!(executable, uid)
+          end
+          operation
+        end
+
+        def authorize!(reference, binding)
+          raise ArgumentError, "invalid authorization reference" unless reference.to_s.match?(ID)
+          decision = @authorizations[reference]
+          raise SecurityError, "authorization reference is unresolved" unless decision.is_a?(Hash)
+          required = %w[operation project_id assignment_id attempt_id input_digest target candidate_head caller_uid]
+          unless required.all? { |key| decision[key] == binding[key] }
+            raise SecurityError, "authorization does not match the exact service request"
+          end
+          raise SecurityError, "authorization has expired" if parse_time(decision["expires_at"]) <= Time.now.utc
+          decision
+        end
+
+        private
+
+        def validate_executable!(path, uid)
+          file = File.stat(path)
+          parent = File.stat(File.dirname(File.realpath(path)))
+          unless [0, uid].include?(file.uid) && [0, uid].include?(parent.uid) &&
+              (file.mode & 0o022).zero? && (parent.mode & 0o022).zero?
+            raise Ace::Lab::InvalidConfigurationError,
+              "configured executable or containing directory is writable by another identity"
+          end
+        rescue Errno::ENOENT, Errno::EACCES
+          raise Ace::Lab::InvalidConfigurationError, "configured executable is unavailable"
+        end
+
+        def inside?(path, root)
+          expanded = File.expand_path(path)
+          base = File.expand_path(root)
+          expanded == base || expanded.start_with?(base + File::SEPARATOR)
+        end
+
+        def parse_time(value)
+          Time.iso8601(value.to_s)
+        rescue ArgumentError
+          raise Ace::Lab::InvalidConfigurationError, "trusted policy has invalid expiry"
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/organisms/service_request_service.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "open3"
+require "ace/assign"
+
+module Ace
+  module Lab
+    module Organisms
+      # Coordinates the generic request contract. ace-assign owns the durable
+      # claim and receipt; this class never writes evidence files directly.
+      class ServiceRequestService
+        def initialize(topology: nil, policy: nil, coordinator: nil, executor: nil, repo_root: Dir.pwd)
+          @topology = topology || TopologyService.from_config
+          @policy = policy
+          @coordinator = coordinator || Ace::Assign::Organisms::AttemptCoordinator.new(repo_root: repo_root)
+          @executor = executor || Molecules::ServiceExecutor.new
+          @repo_root = repo_root
+        end
+
+        def request(project:, assignment:, attempt:, operation:, input_path:, authorization:, request_id:, dry_run: false)
+          {project: project, assignment: assignment, attempt: attempt, request: request_id}.each do |name, value|
+            raise ArgumentError, "invalid #{name} ID" unless value.is_a?(String) &&
+              value.match?(Molecules::ServicePolicy::ID)
+          end
+          input = Atoms::ServiceInput.load(input_path)
+          target = Atoms::ServiceInput.target(input)
+          route = @topology.route(project: project, capability: operation)
+          return route.envelope unless route.ok?
+          service_id = route.data.fetch("entry").fetch("id")
+          trusted = Molecules::GrantResolver.trusted_document(Ace::Lab.authorization_path) unless @policy
+          policy = @policy || Molecules::ServicePolicy.new(trusted)
+          head = current_head
+          binding = {"request_id" => request_id, "assignment_id" => assignment, "attempt_id" => attempt,
+                     "project_id" => project, "operation" => operation,
+                     "input_digest" => Atoms::ServiceInput.digest(input), "target" => target,
+                     "candidate_head" => head, "caller_uid" => Process.uid}
+          binding["authorization"] = authorization
+          binding["service_id"] = service_id
+          binding["caller_uid"] = Process.uid
+          validate_attempt!(binding)
+          begin
+            operation_policy = policy.operation!(operation, project: project, service_id: service_id)
+            policy.authorize!(authorization, binding)
+          rescue SecurityError, Ace::Lab::InvalidConfigurationError
+            @coordinator.reject_service_request(binding, reason: "policy_rejected") unless dry_run
+            raise
+          end
+
+          if dry_run
+            preview = {"outcome" => "accepted", "dry_run" => true, "request_id" => request_id,
+                       "project" => project, "operation" => operation, "service_id" => service_id,
+                       "target" => target, "candidate_head" => head}
+            return {"status" => "ok", "data" => preview}
+          end
+
+          claimed = @coordinator.claim_service_request(binding)
+          return result(claimed) unless claimed["state"] == "accepted" && claimed["journal_commit"]
+
+          # From here, a crash or lost executor response must not authorize a
+          # replay. Record uncertainty before invoking an external process.
+          @coordinator.transition_service_request(request_id, state: "uncertain")
+          receipt = @executor.execute(operation: operation_policy, request: binding, input: input,
+            policy: policy, authorization: authorization)
+          return result(@coordinator.service_request_status(request_id)) if receipt.nil?
+
+          state = receipt.fetch("outcome")
+          full_receipt = Models::ServiceReceipt.build(binding, receipt)
+          result(@coordinator.transition_service_request(request_id, state: state, receipt: full_receipt))
+        rescue ArgumentError => e
+          failure("invalid_input", e.message)
+        rescue SecurityError => e
+          failure("unauthorized", e.message)
+        rescue Ace::Lab::InvalidConfigurationError => e
+          failure("invalid_configuration", e.message)
+        rescue Ace::Assign::AttemptErrors::Conflict => e
+          failure("conflict", e.message)
+        rescue Ace::Assign::AttemptErrors::NotFound, Ace::Assign::AttemptErrors::ReceiptRejected => e
+          failure("invalid_attempt", e.message)
+        rescue Ace::Assign::AttemptErrors::InvalidState => e
+          failure("invalid_attempt", e.message)
+        rescue Ace::Assign::AttemptErrors::EvidenceUnavailable => e
+          failure("evidence_unavailable", e.message)
+        end
+
+        def status(request_id:)
+          request = @coordinator.service_request_status(request_id)
+          return failure("missing", "service request not found") unless request
+          return failure("unauthorized", "caller does not own the request") unless request["caller_uid"] == Process.uid
+          visibility = @topology.services(project: request["project_id"])
+          return visibility.envelope unless visibility.ok?
+          result(request)
+        rescue ArgumentError => e
+          failure("invalid_input", e.message)
+        rescue Ace::Assign::AttemptErrors::EvidenceUnavailable => e
+          failure("evidence_unavailable", e.message)
+        end
+
+        private
+
+        def validate_attempt!(binding)
+          attempt = @coordinator.service_attempt(binding)
+          unless attempt.candidate_head.nil? || attempt.candidate_head == binding["candidate_head"]
+            raise SecurityError, "request is not bound to an active managed attempt"
+          end
+        end
+
+        def current_head
+          out, _stderr, status = Open3.capture3("git", "rev-parse", "HEAD", chdir: @repo_root)
+          raise SecurityError, "candidate head is unavailable" unless status.success?
+          out.strip
+        end
+
+        def result(request)
+          public = request.slice("request_id", "assignment_id", "attempt_id", "project_id", "operation",
+            "input_digest", "target", "candidate_head", "service_id", "state", "receipt")
+          {"status" => "ok", "data" => public.merge("outcome" => request.fetch("state"))}
+        end
+
+        def failure(code, message)
+          {"status" => "error", "error" => {"code" => code, "message" => message}}
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Lab
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

data/lib/ace/lab.rb

@@ -16,16 +16,21 @@ end
 require_relative "lab/atoms/topology_schema"
 require_relative "lab/atoms/binding_freshness"
 require_relative "lab/atoms/public_projection"
+require_relative "lab/atoms/service_input"
+require_relative "lab/models/service_receipt"
 require_relative "lab/models/runtime_binding"
 require_relative "lab/models/topology_entry"
 require_relative "lab/models/query_result"
 require_relative "lab/molecules/topology_loader"
 require_relative "lab/molecules/caller_authorizer"
 require_relative "lab/molecules/grant_resolver"
+require_relative "lab/molecules/service_policy"
+require_relative "lab/molecules/service_executor"
 require_relative "lab/molecules/inventory_query"
 require_relative "lab/molecules/exact_resolver"
 require_relative "lab/molecules/capability_router"
 require_relative "lab/organisms/topology_service"
+require_relative "lab/organisms/service_request_service"
 require_relative "lab/cli"
 
 module Ace

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-lab
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: ace-assign
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.61'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.61'
 - !ruby/object:Gem::Dependency
   name: ace-support-test-helpers
   requirement: !ruby/object:Gem::Requirement
@@ -155,23 +169,29 @@ files:
 - lib/ace/lab.rb
 - lib/ace/lab/atoms/binding_freshness.rb
 - lib/ace/lab/atoms/public_projection.rb
+- lib/ace/lab/atoms/service_input.rb
 - lib/ace/lab/atoms/topology_schema.rb
 - lib/ace/lab/cli.rb
 - lib/ace/lab/cli/commands/agents.rb
 - lib/ace/lab/cli/commands/projects.rb
 - lib/ace/lab/cli/commands/resolve.rb
 - lib/ace/lab/cli/commands/route.rb
+- lib/ace/lab/cli/commands/service.rb
 - lib/ace/lab/cli/commands/services.rb
 - lib/ace/lab/cli/commands/support.rb
 - lib/ace/lab/models/query_result.rb
 - lib/ace/lab/models/runtime_binding.rb
+- lib/ace/lab/models/service_receipt.rb
 - lib/ace/lab/models/topology_entry.rb
 - lib/ace/lab/molecules/caller_authorizer.rb
 - lib/ace/lab/molecules/capability_router.rb
 - lib/ace/lab/molecules/exact_resolver.rb
 - lib/ace/lab/molecules/grant_resolver.rb
 - lib/ace/lab/molecules/inventory_query.rb
+- lib/ace/lab/molecules/service_executor.rb
+- lib/ace/lab/molecules/service_policy.rb
 - lib/ace/lab/molecules/topology_loader.rb
+- lib/ace/lab/organisms/service_request_service.rb
 - lib/ace/lab/organisms/topology_service.rb
 - lib/ace/lab/version.rb
 homepage: https://github.com/cs3b/ace