portage-ucp-decision 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76adc7a80bc65b5fc181bc69c773cea60c9ad1f11a6bb3028add71d895321683
+  data.tar.gz: e6048995c2bbadb78389342bfebe78c25eafefb04a95a158747ba2a97f2120ba
+SHA512:
+  metadata.gz: 6b95c193adcc3c78e19bf01ebdc88eb88b681b5414c081af1d84438a93c025be438e78735637a136e791dc7ca5931d6689451421b2fb7d8062c81a99fc7ed2b1
+  data.tar.gz: b7d76577b2e68e0cea4f5e8701cdcdf8fad1e799fefcb594668e7764fe6d368676e6278b2ede5115d536b34c2c2bf4d44a0e1c237286ab298c9aa2e379fdc9e0

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/); this project is
+pre-1.0, so APIs may still shift between minor versions.
+
+## [Unreleased]
+
+- `OfferRanking` and `EscalationPolicy` now delegate to
+  `portage-ucp`'s `Support::OfferRanking` and `Support::Escalation`, the
+  way `PolicyCheck` already delegated to `PolicyGuard`. Their `Verdict`s
+  and signatures are unchanged. Requires `portage-ucp ~> 0.9`.
+- **Removed surface nothing called**, before the first publish (the README's
+  "What this gem leaves out" says why for each). **Breaking** against the
+  0.1.0 skeleton:
+  - `ConfidenceGate.via_backend` asks a noul only. `type:`, `criteria:` and
+    `proceed_on:` are gone. A choice or score answer now raises
+    `BackendError` ("carried no probability") rather than gating.
+  - `ModelBackends::Answer#probabilities`.
+  - `EscalationPolicy`'s `signals: {mismatch:}` and
+    `EscalationPolicy::ESCALATING_STATUSES`.
+  - `PolicyCheck`'s `risk_signals:` and `Verdict#decision`. The `Verdict`
+    is now `allowed`, `reason`.
+- **A backend failure could escape as a raw exception.** Jev let
+  `Faraday::Error`, `JSON::ParserError` (a non-JSON 2xx) and `KeyError` (no
+  `answers`) through, Laya let `Errno::ENOENT` (a missing
+  `LAYA_INFER_COMMAND`) and `KeyError` through, and `ConfidenceGate` raised
+  `KeyError` for an unanswered question. All are now `BackendError`, with
+  one shared `ModelBackends.parse_answers` for both backends' replies.
+- **Neither backend had a timeout.** Jev could stall a checkout for about two
+  minutes on a hung connection, and Laya forever. Jev now gives up after 5s
+  to connect and 15s to answer. Laya kills its bridge after `timeout:`
+  (default 60s).
+- `LAYA_PYTHON=/opt/venv/bin/python` (a path, not a bare name) was always
+  reported as "isn't on PATH", so the backend never counted as configured.
+- `examples/laya_bridge.py` returned `type`/`confidence`/`value`, which the
+  Ruby side doesn't read, so every noul through it held the purchase. It
+  now emits the per-type keys (`noul`, `choice`, `score`).
+- `Jev#configuration_problem` joins `Laya#configuration_problem` (now
+  public): the reason a backend can't answer yet, for a setup check.
+
+## [0.1.0] - 2026-09-23
+
+- First skeleton: `OfferRanking`, `EscalationPolicy`, `ConfidenceGate`, and
+  `PolicyCheck` as typed decisions, per
+  `docs/plans/system-one-decision-layer.md`.
+- `ConfidenceGate.via_backend` gates on what the model answered, not only on
+  how sure it was. Checked live against Jev:
+  - A noul (the default type) crashed with `NoMethodError` on every call,
+    because Jev sends no `confidence` for a noul. A noul now gates on its
+    yes-probability.
+  - A choice or score proceeded on any confident answer, a confident
+    "escalate" included (Jev answered `escalate` at 0.99 for a live
+    `requires_escalation` checkout). These now need `proceed_on:` (an
+    option, or a Range of score levels), and proceed only on a match.
+- `ModelBackends::Jev` falls back to `TYPESAFE_API_KEY`, the name TypeSafe's
+  own docs use, when `JEV_API_KEY` isn't set.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom Whitbread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,104 @@
+# portage-ucp-decision
+
+The System One decision layer for `portage-ucp` — see
+`docs/plans/system-one-decision-layer.md` for why this exists.
+
+Sits between the agent loop and the Adapter/client layer, turning judgment
+calls that were scattered across skill instructions, `portage-cli`, and
+`portage-ucp` into typed, inspectable decisions:
+
+- `Portage::Ucp::Decision::OfferRanking` — which offer to pick among several.
+  A typed wrapper around `Portage::Ucp::Support::OfferRanking`.
+- `Portage::Ucp::Decision::EscalationPolicy` — hand off vs. keep going. A
+  typed wrapper around `Portage::Ucp::Support::Escalation`.
+- `Portage::Ucp::Decision::ConfidenceGate` — proceed unattended above a
+  threshold.
+- `Portage::Ucp::Decision::PolicyCheck` — a typed wrapper around
+  `Portage::Ucp::PolicyGuard.check!`.
+
+The ranking, escalation and policy rules live in `portage-ucp` core, and
+these three wrap them as `Verdict`s. `portage-cli` calls the core modules
+directly, so it answers the same way with or without this gem. Only
+`ConfidenceGate` and its model backends are unique to this gem.
+
+`ModelBackends::Laya` needs a Python bridge script (it's HuggingFace weights,
+not a hosted API) — see `examples/laya_bridge.py` and set
+`LAYA_BRIDGE_SCRIPT`; a missing or broken bridge raises
+`BackendNotConfiguredError`/`BackendError` with a message naming the exact
+problem (unset, path doesn't exist, `LAYA_PYTHON` not executable, non-zero
+exit, timeout, unreadable reply). The bridge must answer with the same
+`{"answers": {name => answer}}` body Jev returns, each answer keyed by its
+type: `{"type": "noul", "noul": <P(yes)>}`, `{"type": "choice", "choice":
+<option>, "confidence": <c>}`, `{"type": "score", "score": <level>,
+"confidence": <c>}`. `ModelBackends::Jev` reads `JEV_API_KEY` (falling back
+to `TYPESAFE_API_KEY`, TypeSafe's own name for it).
+
+Both backends time out (Jev after 5s to connect and 15s to answer, Laya
+after 60s by default, `timeout:`), and every failure — a timeout, a
+connection error, a reply that isn't that shape — raises a
+`Decision::Error` subclass, so one `rescue Portage::Ucp::Decision::Error`
+covers a backend call. `#configuration_problem` returns the reason a backend
+can't answer yet (nil when it can); `portage doctor` reports it for the
+backend `PORTAGE_DECISION_BACKEND` selects, and says nothing when none is
+selected.
+
+`EscalationPolicy` branches on the literal `requires_escalation` status plus
+an ambiguous-signal case (`signals: {warnings:}`, any warning escalates).
+`ConfidenceGate` compares a score it's handed (`.call`) or gets one from a
+model backend (`.via_backend`, `ModelBackends::Jev`/`ModelBackends::Laya`).
+See the plan doc's "Open questions" section for what's still unresolved.
+
+## Usage
+
+```ruby
+require "portage/ucp/decision"
+
+Portage::Ucp::Decision::EscalationPolicy.call(checkout_status: checkout.status)
+# => #<data Verdict escalate=true, reason=:requires_escalation>
+```
+
+`ConfidenceGate.via_backend` asks one yes/no ("noul") question and gates on
+the probability the backend answered yes, so phrase the question so "yes"
+means "safe to proceed":
+
+```ruby
+jev = Portage::Ucp::Decision::ModelBackends::Jev.new
+
+Portage::Ucp::Decision::ConfidenceGate.via_backend(
+  backend: jev, state: checkout.to_json, question: "safe_to_complete", threshold: 0.8,
+  instructions: "Answer yes only if this checkout is safe to complete without a person reviewing it."
+)
+# => #<data Verdict proceed=false, confidence=0.37, threshold=0.8>
+```
+
+## What this gem leaves out, and why
+
+These were in the first skeleton and were removed before 0.1.0 was
+published, because nothing called them:
+
+- **Choice and score questions in `ConfidenceGate`** (`type:`, `criteria:`,
+  `proceed_on:`). A choice's or score's `confidence` says how sure the model
+  is of whichever answer it gave, so a confident "escalate" clears the
+  threshold; `proceed_on:` was needed just to stop that. A noul's
+  yes-probability is the one number that means "safe to proceed", and it's
+  the only question `portage buy` asks. To use a choice or score, call the
+  backend's `#ask` yourself and read the `Answer`.
+- **`ModelBackends::Answer#probabilities`.** Parsed from the reply but read
+  by nothing.
+- **`EscalationPolicy`'s `mismatch:` signal.** `warnings:` covers it: pass
+  a one-line description of the mismatch.
+- **`EscalationPolicy::ESCALATING_STATUSES`.** It only ever held
+  `requires_escalation`, which is `Portage::Ucp::Support::Escalation::STATUS`.
+- **`PolicyCheck`'s `risk_signals:`, and the `decision:` field on its
+  `Verdict`.** Nothing computes a risk signal yet (merchant age,
+  TLS/manifest signing, escalation rate), and `decision:` repeated
+  `allowed`/`reason`. A caller with its own signal can deny before calling
+  `PolicyCheck`.
+
+## Development
+
+```
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```

data/lib/portage/ucp/decision/confidence_gate.rb

@@ -0,0 +1,57 @@
+module Portage
+  module Ucp
+    module Decision
+      # docs/plans/system-one-decision-layer.md § Responsibilities 3.
+      #
+      # Wholly new — no precedent in this repo. `Confirmer` is binary
+      # (confirm or don't); this is the graded threshold a caller sits in
+      # front of it. Where the `confidence:` score itself comes from was the
+      # doc's open question — `.via_backend` below answers it for a model
+      # backend (ModelBackends::Jev/Laya); `.call` stays the pure comparator
+      # for a caller with its own heuristic score.
+      module ConfidenceGate
+        Verdict = Data.define(:proceed, :confidence, :threshold)
+
+        # @param confidence [Float] 0.0..1.0.
+        # @param threshold [Float] 0.0..1.0 — the caller's own risk posture,
+        #   not something this gate defaults or infers.
+        def self.call(confidence:, threshold:)
+          Verdict.new(proceed: confidence >= threshold, confidence: confidence, threshold: threshold)
+        end
+
+        # Asks a ModelBackends backend one yes/no ("noul") question and gates
+        # on the probability it answered yes. Phrase the question so "yes"
+        # means "safe to proceed". Jev sends no separate `confidence` for a
+        # noul (docs.typesafe.ai/api — confirmed live:
+        # `{"type":"noul","noul":0.37}`), and none is needed: the
+        # yes-probability is the thing to threshold.
+        #
+        # Only a noul, on purpose. A choice's or score's `confidence` is how
+        # sure the model is of whichever answer it gave, so a confident
+        # "escalate" would clear the threshold (Jev did exactly that, at
+        # 0.99, for a live `requires_escalation` checkout). A caller that
+        # wants a choice or score can ask the backend directly with
+        # `#ask` and read the answer itself.
+        #
+        # @param backend [#ask] a ModelBackends::Jev/Laya instance (or
+        #   anything answering the same `#ask(state:, questions:)` shape).
+        # @param state [String]
+        # @param question [String] the key the answer comes back under.
+        # @param instructions [String] what the backend should evaluate.
+        # @param threshold [Float]
+        # @return [Verdict]
+        def self.via_backend(backend:, state:, question:, instructions:, threshold:)
+          asked = { question => ModelBackends::Question.new(type: "noul", instructions: instructions) }
+          answer = backend.ask(state: state, questions: asked).fetch(question) do
+            raise Portage::Ucp::Decision::BackendError, "backend returned no answer for #{question.inspect}"
+          end
+          unless answer.value.is_a?(Numeric)
+            raise Portage::Ucp::Decision::BackendError, "noul answer carried no probability: #{answer.to_h}"
+          end
+
+          call(confidence: answer.value, threshold: threshold)
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/errors.rb

@@ -0,0 +1,20 @@
+module Portage
+  module Ucp
+    module Decision
+      class Error < StandardError; end
+
+      # Raised by a ModelBackend when it's asked to run without whatever it
+      # needs to actually reach a model — an API key (Jev) or a local
+      # inference command (Laya) — rather than failing further in with a
+      # confusing HTTP or ENOENT error.
+      class BackendNotConfiguredError < Error; end
+
+      # Raised by a ModelBackend when the call itself fails — a non-2xx
+      # response (Jev) or a non-zero exit status (Laya).
+      class BackendError < Error; end
+
+      # Raised by ModelBackends.resolve for a name not in ModelBackends::REGISTRY.
+      class UnknownBackendError < Error; end
+    end
+  end
+end

data/lib/portage/ucp/decision/escalation_policy.rb

@@ -0,0 +1,29 @@
+require "portage/ucp"
+
+module Portage
+  module Ucp
+    module Decision
+      # docs/plans/system-one-decision-layer.md § Responsibilities 2.
+      #
+      # A typed wrapper around `Portage::Ucp::Support::Escalation`, the way
+      # PolicyCheck wraps `PolicyGuard`. The rule lives in core: the literal
+      # `requires_escalation` status wins, then a mismatch the caller found.
+      # That covers the doc's "ambiguous signal" case, a merchant surfacing
+      # a mismatch that isn't literally `requires_escalation` but should
+      # still stop here. `signals: {warnings:}` takes the same
+      # `warnings: [String]` array `portage buy` puts on its report.
+      module EscalationPolicy
+        Verdict = Data.define(:escalate, :reason)
+
+        # @param checkout_status [String] a Checkout#status value.
+        # @param signals [Hash] `warnings:` an Array of human-readable
+        #   mismatch strings. Any element escalates; none is required.
+        def self.call(checkout_status:, signals: {})
+          reason = Portage::Ucp::Support::Escalation.reason(checkout_status: checkout_status,
+                                                            warnings: signals[:warnings])
+          Verdict.new(escalate: !reason.nil?, reason: reason)
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/model_backends/answer.rb

@@ -0,0 +1,47 @@
+require "json"
+
+module Portage
+  module Ucp
+    module Decision
+      module ModelBackends
+        # A single typed question sent to a backend — the wire shape both
+        # Jev (api.typesafe.ai/v1/systemone) and the Laya subprocess
+        # contract share. `criteria` is a Hash for `type: "choice"`, an
+        # Array for `type: "score"`, absent for `type: "noul"` (yes/no).
+        Question = Data.define(:type, :instructions, :criteria) do
+          def initialize(type:, instructions:, criteria: nil) = super
+
+          def to_wire_h = { "type" => type, "instructions" => instructions, "criteria" => criteria }.compact
+        end
+
+        # A single typed answer back from a backend. `value` is the answer
+        # itself (a choice's option, a score's level, a noul's probability of
+        # yes). `confidence` is how sure the model is of a choice or score —
+        # Jev sends none for a noul, so ConfidenceGate gates a noul on
+        # `value` instead.
+        Answer = Data.define(:type, :confidence, :value) do
+          def initialize(type:, confidence:, value: nil) = super
+        end
+
+        # The `{"answers": {name => {...}}}` body both backends return, as
+        # Answers. Anything that isn't that shape — invalid JSON, no
+        # `answers`, an answer that isn't an object — is a BackendError
+        # naming `source`, so a caller rescuing Decision::Error sees every
+        # bad reply rather than a stray JSON::ParserError or KeyError.
+        #
+        # @param raw [String] the backend's response body / stdout.
+        # @param source [String] who answered, for the error message.
+        # @return [Hash{String => Answer}]
+        def self.parse_answers(raw, source:)
+          JSON.parse(raw).fetch("answers").transform_values do |answer|
+            Answer.new(type: answer["type"], confidence: answer["confidence"],
+                       value: answer["choice"] || answer["score"] || answer["noul"])
+          end
+        rescue JSON::ParserError, KeyError, TypeError, NoMethodError => e
+          raise Portage::Ucp::Decision::BackendError,
+                "#{source} returned an unreadable answer (#{e.class}: #{e.message}): #{raw.to_s[0, 300].inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/model_backends/jev.rb

@@ -0,0 +1,85 @@
+require "json"
+require "faraday"
+
+module Portage
+  module Ucp
+    module Decision
+      module ModelBackends
+        # Client for TypeSafe AI's Jev — the "System One Model" the plan doc's
+        # title borrowed its name from (docs.typesafe.ai/introduction/quickstart).
+        # A hosted decision API: POST state + typed questions, get back typed
+        # answers with a calibrated `confidence` per answer.
+        class Jev
+          BASE_URL = "https://api.typesafe.ai/v1/systemone".freeze
+          DEFAULT_MODEL = "jev-latest".freeze
+          # This gem's own name for the credential, matching this backend's
+          # name in the registry. TYPESAFE_API_KEY — the name TypeSafe's own
+          # docs and SDKs use — is read as a fallback, so a key already set up
+          # for TypeSafe works here without being copied to a second name.
+          # Seconds. A confidence check sits in front of a checkout the
+          # shopper is waiting on; Net::HTTP's defaults would stall it for up
+          # to two minutes on a hung connection.
+          OPEN_TIMEOUT = 5
+          TIMEOUT = 15
+          ENV_KEY = "JEV_API_KEY".freeze
+          FALLBACK_ENV_KEY = "TYPESAFE_API_KEY".freeze
+
+          def self.env_api_key
+            [ENV_KEY, FALLBACK_ENV_KEY].map { |key| ENV.fetch(key, nil).to_s.strip }.find { |key| !key.empty? }
+          end
+
+          def initialize(api_key: self.class.env_api_key, model: DEFAULT_MODEL, connection: nil)
+            @api_key = api_key
+            @model = model
+            @connection = connection ||
+                          Faraday.new(url: BASE_URL, request: { open_timeout: OPEN_TIMEOUT, timeout: TIMEOUT })
+          end
+
+          def configured? = configuration_problem.nil?
+
+          # @return [String, nil] why this backend can't answer yet, or nil
+          #   when it can — same contract as Laya#configuration_problem.
+          def configuration_problem
+            return nil unless @api_key.to_s.strip.empty?
+
+            "#{ENV_KEY} is not set (nor #{FALLBACK_ENV_KEY}) — get a key at https://console.typesafe.ai " \
+              "and set #{ENV_KEY}"
+          end
+
+          # @param state [String] the text (or JSON-serialized context) to
+          #   evaluate — a checkout, an offer list, a merchant signal.
+          # @param questions [Hash{String => Question}]
+          # @return [Hash{String => Answer}]
+          def ask(state:, questions:)
+            problem = configuration_problem
+            raise Portage::Ucp::Decision::BackendNotConfiguredError, problem if problem
+
+            response = post(state, questions)
+            raise_for_status!(response)
+            ModelBackends.parse_answers(response.body, source: "Jev")
+          rescue Faraday::Error => e
+            raise Portage::Ucp::Decision::BackendError, "Jev request failed: #{e.class}: #{e.message}"
+          end
+
+          private
+
+          def post(state, questions)
+            @connection.post("") do |req|
+              req.headers["Authorization"] = "Bearer #{@api_key}"
+              req.headers["Content-Type"] = "application/json"
+              req.body = JSON.generate(state: state, model: @model,
+                                       questions: questions.transform_values(&:to_wire_h))
+            end
+          end
+
+          def raise_for_status!(response)
+            return if response.status.between?(200, 299)
+
+            raise Portage::Ucp::Decision::BackendError,
+                  "Jev request failed: #{response.status} #{response.body.to_s[0, 300]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/model_backends/laya.rb

@@ -0,0 +1,133 @@
+require "json"
+require "open3"
+
+module Portage
+  module Ucp
+    module Decision
+      module ModelBackends
+        # Client for Laya (huggingface.co/convaiinnovations/laya) — a local,
+        # open-weights (Apache 2.0) decision-classification model, not a
+        # hosted API. It ships as ModernBERT/mmBERT weights invoked through
+        # Python (HuggingFace `transformers`, or the `laya` SDK's
+        # `laya.load()`), and this is a Ruby gem, so this backend shells out
+        # to a Python "bridge script" instead of embedding the model. The
+        # script must speak this gem's own stdin/stdout JSON contract —
+        # `{"state", "questions"}` in, `{"answers"}` out, the same shape
+        # ModelBackends::Jev uses — not any interface Laya's Python side
+        # defines itself. Writing that script is the caller's job (a
+        # starting point is at `examples/laya_bridge.py` in this gem); this
+        # class only owns the Ruby-side contract and the two failure modes
+        # around it not being there yet: no bridge configured at all, and a
+        # configured one that's missing or fails at call time.
+        class Laya
+          DEFAULT_PYTHON = "python3".freeze
+          ENV_BRIDGE_SCRIPT_KEY = "LAYA_BRIDGE_SCRIPT".freeze
+          ENV_PYTHON_KEY = "LAYA_PYTHON".freeze
+          # Escape hatch for a caller whose bridge isn't `python3 <script>` —
+          # a container entrypoint, a wrapper shell script, anything already
+          # executable on its own. Takes precedence over bridge_script/python
+          # since it's a deliberate override, not a default.
+          ENV_COMMAND_KEY = "LAYA_INFER_COMMAND".freeze
+          # Seconds. Generous, since the bridge loads model weights on every
+          # call, but bounded: a stuck bridge must hold the purchase, not
+          # hang it.
+          DEFAULT_TIMEOUT = 60
+
+          def initialize(bridge_script: ENV.fetch(ENV_BRIDGE_SCRIPT_KEY, nil),
+                         python: ENV.fetch(ENV_PYTHON_KEY, DEFAULT_PYTHON),
+                         command: ENV.fetch(ENV_COMMAND_KEY, nil), timeout: DEFAULT_TIMEOUT)
+            @bridge_script = bridge_script
+            @python = python
+            @custom_command = command
+            @timeout = timeout
+          end
+
+          def configured? = configuration_problem.nil?
+
+          # @param state [String]
+          # @param questions [Hash{String => Question}]
+          # @return [Hash{String => Answer}]
+          def ask(state:, questions:)
+            problem = configuration_problem
+            raise Portage::Ucp::Decision::BackendNotConfiguredError, problem if problem
+
+            stdout, stderr, status = run(request_json(state, questions))
+            raise Portage::Ucp::Decision::BackendError, "Laya bridge failed: #{stderr}" unless status.success?
+
+            ModelBackends.parse_answers(stdout, source: "Laya bridge")
+          end
+
+          # nil means "configured" — anything else is the reason it isn't,
+          # returned rather than raised so #configured?, #ask and a setup
+          # check (portage doctor) share one check without swallowing an
+          # exception.
+          def configuration_problem
+            return nil if @custom_command
+
+            unless @bridge_script
+              return "no Laya bridge configured — set #{ENV_BRIDGE_SCRIPT_KEY} to a Python script implementing " \
+                     "the state/questions -> answers JSON contract (see examples/laya_bridge.py), or " \
+                     "#{ENV_COMMAND_KEY} for a fully custom command"
+            end
+
+            return "#{ENV_BRIDGE_SCRIPT_KEY}=#{@bridge_script} does not exist" unless File.file?(@bridge_script)
+
+            return "#{ENV_PYTHON_KEY}=#{@python} isn't an executable on PATH" unless which(@python)
+
+            nil
+          end
+
+          private
+
+          def command = @custom_command ? Array(@custom_command) : [@python, @bridge_script]
+
+          def request_json(state, questions)
+            JSON.generate(state: state, questions: questions.transform_values(&:to_wire_h))
+          end
+
+          # Open3.capture3 with a deadline: the child is killed, not left
+          # running, when it overruns. A command that can't start at all
+          # (ENOENT, EACCES) is a BackendError like any other bridge failure.
+          def run(input)
+            Open3.popen3(*command) do |stdin, stdout, stderr, wait|
+              readers = [Thread.new { stdout.read }, Thread.new { stderr.read }]
+              write_request(stdin, input)
+              timed_out = wait.join(@timeout).nil?
+              Process.kill("KILL", wait.pid) if timed_out
+              # After a kill, a grandchild (a wrapper's python) can still hold
+              # the pipes open, so don't wait on the readers indefinitely.
+              out, err = readers.map { |reader| reader.join(timed_out ? 1 : nil)&.value.to_s }
+              raise Portage::Ucp::Decision::BackendError, "Laya bridge timed out after #{@timeout}s" if timed_out
+
+              [out, err, wait.value]
+            end
+          rescue SystemCallError, IOError => e
+            raise Portage::Ucp::Decision::BackendError, "Laya bridge couldn't run #{command.first}: #{e.message}"
+          end
+
+          # A bridge that exits without reading its stdin closes the pipe
+          # early. Its exit status and stderr say why, so that's reported
+          # rather than the EPIPE.
+          def write_request(stdin, input)
+            stdin.write(input)
+          rescue Errno::EPIPE
+            nil
+          ensure
+            stdin.close
+          end
+
+          # A path (LAYA_PYTHON=/opt/venv/bin/python) is checked as-is; a
+          # bare name is looked up on PATH.
+          def which(command)
+            return (executable_file?(command) ? command : nil) if command.include?("/")
+
+            ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |dir| File.join(dir, command) }
+               .find { |path| executable_file?(path) }
+          end
+
+          def executable_file?(path) = File.executable?(path) && !File.directory?(path)
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/model_backends.rb

@@ -0,0 +1,31 @@
+require_relative "errors"
+require_relative "model_backends/answer"
+require_relative "model_backends/jev"
+require_relative "model_backends/laya"
+
+module Portage
+  module Ucp
+    module Decision
+      # docs/plans/system-one-decision-layer.md's open question — "Confidence
+      # gating needs a defined scale and source" — resolved here for two
+      # concrete, swappable model backends: Jev (TypeSafe AI's hosted
+      # "System One Model", the plan doc's own namesake) and Laya (an
+      # open-weights local model). Both speak the same `#ask(state:,
+      # questions:) -> Hash{String => Answer}` shape, so ConfidenceGate can
+      # threshold either one's `confidence` without knowing which is behind
+      # it.
+      module ModelBackends
+        REGISTRY = { "jev" => Jev, "laya" => Laya }.freeze
+
+        # @param name [String, Symbol] a REGISTRY key.
+        # @return a new backend instance.
+        def self.resolve(name, **)
+          REGISTRY.fetch(name.to_s) do
+            raise Portage::Ucp::Decision::UnknownBackendError,
+                  "unknown decision model backend #{name.inspect} — known: #{REGISTRY.keys.join(', ')}"
+          end.new(**)
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/offer_ranking.rb

@@ -0,0 +1,27 @@
+require "portage/ucp"
+
+module Portage
+  module Ucp
+    module Decision
+      # docs/plans/system-one-decision-layer.md § Responsibilities 1.
+      #
+      # A typed wrapper around `Portage::Ucp::Support::OfferRanking`, the
+      # way PolicyCheck wraps `PolicyGuard`. The rule itself lives in core:
+      # buyable candidates first, then cheapest, then unpriced. portage-cli
+      # calls core directly, so its ranking can't drift from this one.
+      module OfferRanking
+        # A caller's candidate, wrapped just enough for ranking to compare
+        # it — the caller keeps whatever richer type (Product, a CLI hash,
+        # an agent-loop's own struct) it already has on `#offer`.
+        Candidate = Data.define(:offer, :buyable, :amount)
+
+        # @param candidates [Array<Candidate>]
+        # @return [Array<Candidate>] the same candidates, stable-sorted
+        #   buyable-first, cheapest-first, unpriced-last.
+        def self.call(candidates)
+          Portage::Ucp::Support::OfferRanking.rank(candidates) { |candidate| [candidate.buyable, candidate.amount] }
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/policy_check.rb

@@ -0,0 +1,28 @@
+require "portage/ucp"
+
+module Portage
+  module Ucp
+    module Decision
+      # docs/plans/system-one-decision-layer.md § Responsibilities 4.
+      #
+      # Closest responsibility to done: `Portage::Ucp::PolicyGuard` already
+      # covers per-transaction cap, rolling cap, velocity, and merchant
+      # allowlist. This wraps it as a typed `Verdict` instead of a raised
+      # exception, so a caller gets the same inspectable shape as the other
+      # three decisions in this gem.
+      module PolicyCheck
+        Verdict = Data.define(:allowed, :reason)
+
+        # @return [Verdict]
+        def self.call(amount:, currency:, merchant:, token_ref:, policy: Portage::Ucp::Policy.load,
+                      transaction_log: Portage::Ucp::Support::TransactionLog.new)
+          Portage::Ucp::PolicyGuard.check!(amount: amount, currency: currency, merchant: merchant,
+                                           token_ref: token_ref, policy: policy, transaction_log: transaction_log)
+          Verdict.new(allowed: true, reason: nil)
+        rescue Portage::Ucp::PolicyViolationError => e
+          Verdict.new(allowed: false, reason: e.reason)
+        end
+      end
+    end
+  end
+end

data/lib/portage/ucp/decision/version.rb

@@ -0,0 +1,7 @@
+module Portage
+  module Ucp
+    module Decision
+      VERSION = "0.1.0".freeze
+    end
+  end
+end

data/lib/portage/ucp/decision.rb

@@ -0,0 +1,11 @@
+# docs/plans/system-one-decision-layer.md — the typed decision layer that
+# sits between the agent loop and the Adapter/client layer: offer ranking,
+# escalation policy, confidence gating, and policy checks as inspectable
+# data, not control flow scattered across skill instructions and the CLI.
+require_relative "decision/version"
+require_relative "decision/errors"
+require_relative "decision/model_backends"
+require_relative "decision/offer_ranking"
+require_relative "decision/escalation_policy"
+require_relative "decision/confidence_gate"
+require_relative "decision/policy_check"

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: portage-ucp-decision
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tom Whitbread
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: portage-ucp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.88'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.24'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: 'The judgment calls between the agent loop and the Adapter/client layer,
+  as typed, inspectable decisions instead of control flow scattered across skill instructions
+  and the CLI: which offer to pick (OfferRanking), hand off vs. keep going (EscalationPolicy),
+  whether a result is confident enough to act on unattended (ConfidenceGate), and
+  a typed wrapper around Portage::Ucp::PolicyGuard (PolicyCheck). See docs/plans/system-one-decision-layer.md.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/portage/ucp/decision.rb
+- lib/portage/ucp/decision/confidence_gate.rb
+- lib/portage/ucp/decision/errors.rb
+- lib/portage/ucp/decision/escalation_policy.rb
+- lib/portage/ucp/decision/model_backends.rb
+- lib/portage/ucp/decision/model_backends/answer.rb
+- lib/portage/ucp/decision/model_backends/jev.rb
+- lib/portage/ucp/decision/model_backends/laya.rb
+- lib/portage/ucp/decision/offer_ranking.rb
+- lib/portage/ucp/decision/policy_check.rb
+- lib/portage/ucp/decision/version.rb
+homepage: https://github.com/tomtom87/Portage/tree/main/portage-ucp-decision
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tomtom87/Portage/tree/main/portage-ucp-decision
+  changelog_uri: https://github.com/tomtom87/Portage/blob/main/portage-ucp-decision/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: System One decision layer for portage-ucp — offer ranking, escalation, confidence,
+  policy
+test_files: []