lex-llm-vertex 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '00809f0bdd3bed557d5b9118a9fc70d312c51fd76186b8094a75e8cd466aa0cb'
-  data.tar.gz: 3aef7dbcaa603e84ddc908d70a4e5725f05a7e6976aa713cddc3bbdb8ffaf375
+  metadata.gz: 6d4f8692faa325cfbd5b8d72ed00208dc1023d112a688f92d245efa8acb1e57b
+  data.tar.gz: 514f813574d1c555f4fd35374359e226b79f968ae2601992efb0861f15b2fd2d
 SHA512:
-  metadata.gz: 655b4165c7cc60df1203070fe7d0018b7286deefb622d8fcbdd785cedbbb016a7bb2e8c35dd78acccfd49dfe3d9c16e46c3a4191c25457ad580de48c93dae8a6
-  data.tar.gz: f3cc8a26e1bfebd588dc4c13107c6b99922468e6f11b66fed68c005305c85dabccece0e90c5e774aa633df4465f555f8f1456492c941cd9c79a8a5c36b3f56ec
+  metadata.gz: 5fb6e60b85142ec54bf5d0bc637763e2ea78e4b028ba1d376965e5c2557199313ddeff19859b77c13f39957f6d92c5f3e2ae8478b316650299bc245d1469e0e0
+  data.tar.gz: ab51ecb1ef789105c321028408f31fd4094084f61d406f9693b948acae0693976f38a9225b36d86c7b3d6a1063e0fbd6d3f8f0bfe29bde42e5db51f5a9c31d41

data/.rubocop.yml

@@ -24,6 +24,10 @@ Metrics/PerceivedComplexity:
   Enabled: false
 Metrics/ClassLength:
   Enabled: false
+# default ModuleLength (100) is too strict for a discovery runner carrying the
+# full evidence-building surface. Length is still bounded (Max 350).
+Metrics/ModuleLength:
+  Max: 350
 RSpec/MultipleExpectations:
   Enabled: false
 RSpec/ExampleLength:

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.3.5] - 2026-08-20
+
+0.8.0 conformance release against the lex-llm 0.8.0 contract cut.
+
+### Changed
+- Migrate the provider to the lex-llm 0.8.0 canonical contract: `chat`/`stream_chat` run through the base's single `complete` funnel (central `enforce_canonical_messages!` — the provider no longer re-implements the check), `render_payload` renders the Vertex wire FROM canonical values, `parse_completion_response` returns a `Canonical::Response`, and `build_chunk` yields `Canonical::Chunk` objects through the base `Streaming` module (real SSE chunk lifecycle ending in exactly one done chunk).
+- Enforce the canonical dispatch boundary end to end: the callable's chat, stream_chat, and count_tokens operations keep the shared `Provider#enforce_canonical_messages!` call at the exact-execution boundary, and the base funnel enforces centrally before rendering — plain-Hash messages (the 2026-08-19 incident class) raise a loud ArgumentError at both boundaries, and the dual-shape render-seam tolerance (provider-native `Message` acceptance) is gone.
+- `count_tokens` returns the provider's real `totalTokens` as an Integer and raises `NotImplementedError` for non-generateContent partner models (unsupported operations fail loud; the discovery writer publishes `:unsupported` operation evidence for them).
+- `embed` returns the 0.8.0 documented artifact `{ text:, model:, embedding:, usage: Canonical::Usage }`.
+- The provider's offering read path now serves activated inventory offerings from the SSOT registry snapshot (base `discover_offerings`, 07 C5); the discovery actor's writer remains the sole publication path.
+- Raise the `lex-llm` dependency floor to 0.8.0.
+
+### Added
+- Vertex wire `finishReason` spellings map to canonical stop reasons via `StopReasonMapping#stop_reason_map_additions`; sync responses and rawPredict partner responses carry `stop_reason`.
+- Vertex `thought` parts surface as a canonical `Thinking` member (content + `thoughtSignature`) in sync responses and as `thinking_delta` chunks in streams, instead of being dropped.
+- The fleet worker runner dispatches protocol-v3 exact-only envelopes against the SSOT registry (`ProviderResponder.call` with `registry:`).
+- Conformance: the ssot_v3 spec runs the shared kit's B1 (central canonical enforcement) and B2 (canonical outputs, asserted by type) groups against the real callable boundary, and the raw-string model dispatch examples now feed canonical messages through the real render path.
+- Keep a local-tree `lex-llm` path dependency in the test group so the adjacent checkout resolves against the unreleased 0.8.0 cut during development.
+
+### Removed
+- Legacy type construction in the parse paths: `Llm::Message` / `Llm::Chunk` / `Llm::ToolCall` from completion parsing, `Llm::Content` / `Llm::Content::Raw` handling in the content renderer, and `Llm::Embedding` from the embed path (replaced by `Canonical::*` types and the documented embedding artifact).
+- The provider-native offering production path: the `discover_offerings` override, `offering_for` / `static_offerings` / `offering_from_live_model` / `offering_from_model` / `build_offering` (the `Routing::ModelOffering` production site), and the now-dead offering-feed helpers.
+- The discovery actor's `Inventory::ScopedRefresher::LegacyCoordinatorAdapter` wiring (the file and the mixed-version window it served are deleted in lex-llm 0.8.0); the Publisher is a direct Registry wrapper.
+
 ## [0.3.4] - 2026-08-19
 
 ### Changed

data/Gemfile

@@ -2,10 +2,15 @@
 
 source 'https://rubygems.org'
 
-gem 'lex-llm'
-
 gemspec
 
+# Local-tree resolution: use the adjacent lex-llm checkout when present so the
+# 0.8.0 conformance work resolves against the unreleased 0.8.0 cut.
+group :test do
+  lex_llm_path = File.expand_path('../lex-llm', __dir__)
+  gem 'lex-llm', path: lex_llm_path if Dir.exist?(lex_llm_path)
+end
+
 group :development do
   gem 'bundler', '>= 2.0'
   gem 'rake', '>= 13.0'

data/RULES.md

@@ -0,0 +1,97 @@
+RULES.md — Legion LLM Architecture Law
+These rules apply to every task, file, repository, agent, model, session, test, refactor, migration, incident, and release.
+The requested task defines what may change. These rules define how the system ALWAYS works.
+Every rule remains active 100% of the time. If requested work conflicts with these rules, stop and surface the conflict before changing code.
+These are architecture laws. Scope, compatibility, urgency, convenience, tests, existing behavior, and model judgment do not change them.
+1. Canonical is the only internal language.
+Every client translates client wire -> Canonical before shared execution.
+Shared execution carries Canonical through context, tools, routing, direct dispatch, fleet dispatch, and response handling.
+Every provider translates Canonical -> provider wire at the provider boundary, then provider wire -> Canonical before returning to shared execution.
+Every internal boundary validates the Canonical type it is defined to receive and raises immediately when that contract is violated.
+Client Wire -> Client Translator -> Canonical -> Shared Execution -> Canonical -> Provider Translator -> Provider Wire.
+2. Serialization preserves Canonical.
+Transport may serialize Canonical state. The receiving transport boundary ALWAYS rehydrates the exact Canonical type before execution continues.
+Fleet follows Canonical -> serialize -> wire -> deserialize -> rehydrate Canonical -> Canonical.
+Serialization changes encoding only. Ownership, identity, model, operation, capability, selection, and meaning remain exactly the same.
+After rehydration, shared execution continues only with Canonical objects.
+3. Every authoritative fact has exactly one owner.
+The owner creates the fact once. Every downstream layer carries, projects, serializes, rehydrates, verifies, or executes that exact fact.
+A downstream layer receiving missing or contradictory authoritative state raises and returns the defect to the owning layer.
+Authority ALWAYS moves forward by preservation.
+Authority is created once and is never recreated downstream.
+4. Requirements describe the request. Inventory describes reality. Router chooses. Dispatch executes.
+Canonical request construction owns request semantics. RequestRequirements expresses operation, capabilities, modality, context, output, tools, and explicit pins.
+Providers publish exact executable facts into Inventory. Inventory owns canonical instance, offering, lane, capability, context, quota, health, and published weight state.
+Router.next_lane consumes Requirements plus one immutable Inventory snapshot and produces one authoritative Selection.
+Dispatch executes that Selection exactly. Once Selection exists, routing is finished.
+5. Inventory facts are immutable executable facts.
+Providers publish exact instances and complete offering snapshots through the Inventory publication contract.
+Identity, capability evidence, context evidence, quota domains, availability, and write-time weights are consumed from published Inventory state.
+A changed fact becomes authoritative only through the owning publication or reconciliation path and a new Inventory snapshot.
+Routing reads Inventory. Dispatch verifies and executes Inventory-backed Selection.
+6. Identity, capabilities, weights, and context policy retain exact ownership.
+Inventory::Identity owns instance, offering, and lane identity; canonical instance identity is provider family plus the operator/configured instance name; physical endpoint data remains secondary.
+Providers publish capability evidence. Requirements state required capabilities. Candidate evaluation compares the two and determines capability eligibility.
+The weight owner computes lane weight at publication time; Inventory stores it; ranking consumes that stored weight; a stored zero disables the lane.
+Preferred-context binning orders eligible candidates into preference bands and preserves eligibility. Capability, health, binning, and weight ALWAYS retain distinct meanings.
+7. Routing chooses exactly once.
+Router.next_lane is the sole routing authority.
+Candidate evaluation determines eligibility from Requirements and Inventory. Ranking orders eligible candidates from published routing facts.
+Selection freezes the exact provider, instance, offering, lane, model, operation, and routing identity required for execution.
+Every downstream component consumes the Selection it receives.
+Selection is preserved, not reconstructed.
+8. Exact execution stays exact through every boundary.
+Direct dispatch executes the exact Selection-derived binding it receives.
+Fleet dispatch serializes and signs that exact binding; fleet validation verifies it; fleet rehydration restores it; worker resolution verifies it against authoritative Inventory.
+The selected provider, instance, offering, lane, model, and operation remain identical through projection, signing, transport, validation, rehydration, resolution, and callable invocation.
+A mismatch raises before provider execution.
+An exact execution request ALWAYS remains exact execution.
+9. Health and errors preserve one authoritative meaning.
+Inventory owns exact-instance availability. An authoritative instance-unavailable result removes that exact instance; readiness probing owns recovery; successful readiness republish re-admits it.
+Overload, timeout, rate limit, model-not-ready, and transient provider failures remain request-local according to ProviderOutcome semantics.
+The first layer that can authoritatively classify an error performs that classification once. Every downstream layer preserves it.
+Programming errors remain programming errors. Contract violations remain contract violations. Routing exhaustion remains the defined typed Rejection.
+10. Compatibility exists only at explicit edges.
+Supported legacy clients and protocols are translated into the current Canonical and SSOT architecture at explicit compatibility boundaries.
+Shared execution remains Canonical. Routing remains SSOT-driven. Exact execution remains exact.
+Compatibility code adapts an external contract to the current internal architecture.
+The current internal architecture ALWAYS has one representation, one routing authority, one identity system, and one execution truth.
+11. Fix every defect at its owner.
+Trace the incorrect value to the layer that owns it, then fix that owner.
+Fix client wire in the client translator; Canonical shape in Canonical construction; Requirements in Requirements construction; provider facts in publication; identity in Inventory identity; weights in publication/reconciliation.
+Fix eligibility in candidate evaluation; ordering in ranking; choice in Router.next_lane; execution preservation in dispatch; provider wire in the provider translator.
+The layer where a defect becomes visible is evidence. The owning layer is where the correction belongs.
+12. A discovered issue remains in its owning domain.
+Complete the requested task inside its stated scope.
+When investigation exposes a separate defect owned by another architectural domain, record and surface it as separate work unless the requested task is explicitly expanded.
+Routing work consumes existing Canonical Requirements and Inventory facts. Canonical work changes Canonical contracts. Provider work changes publication or translation. Transport work changes transport.
+Nearby code never changes ownership. “While we are here” never changes architecture.
+13. N x N ALWAYS converges through Canonical.
+Equivalent client semantics produce equivalent Canonical state before shared execution. Every provider consumes the same Canonical semantics for the same request.
+When two paths disagree, capture the state at every involved boundary and locate the FIRST point where Canonical meaning diverges.
+Fix that first divergent boundary, then run the exact failing path again.
+Client behavior is proven at client-wire <-> Canonical. Provider behavior is proven at Canonical <-> provider-wire. Shared execution is proven with Canonical throughout.
+14. Debug from captured authoritative state.
+Capture the actual input at the failing boundary before reasoning from symptoms.
+For translation or transport defects, capture Canonical immediately before and after every involved boundary.
+For routing or dispatch defects, capture Requirements, relevant Inventory facts, Selection, execution binding, and ProviderOutcome.
+Compare each captured value to the contract owned by that layer. Find the first divergence. Fix its owner. Re-run the exact path.
+Then inspect sibling implementations for the same defect class.
+15. Tests prove the real boundary and the invariant.
+A boundary test exercises the real boundary it claims to protect.
+Fleet tests exercise real serialization, deserialization, Canonical rehydration, signing, validation, exact resolution, and callable dispatch.
+Provider tests exercise the real callable boundary and provider translator. Routing tests exercise real Requirements, Inventory records, candidate evaluation, ranking, and Selection.
+Regression tests prove the violated invariant, not only the observed symptom.
+A green suite is release evidence only when the tested path traverses the real architecture.
+16. Shared contracts are consumed directly.
+Shared Canonical types own execution representation. Shared Inventory types own inventory state. Shared Routing types own routing state.
+Shared taxonomy owns canonical mappings. Shared ProviderOutcome owns provider-neutral outcomes. Shared fleet protocol owns exact execution claims.
+Every repository consumes these shared owners directly.
+A defect in one shared boundary triggers an audit of every sibling implementation of that boundary. Fix the shared owner centrally whenever the defect belongs to a shared contract.
+17. Architecture is the release gate.
+Every change preserves every rule in this file.
+Tests, compatibility, historical behavior, migration phase, patch urgency, nearby code, task wording, and model judgment are evaluated UNDER these rules.
+A contradiction between existing behavior and these rules is surfaced as an architecture conflict and resolved at the owning boundary before release.
+Limited scope means do less. Limited scope NEVER means fewer rules apply.
+These rules apply 100% of the time.
+These are the law.

data/lex-llm-vertex.gemspec

@@ -27,5 +27,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'legion-logging', '>= 1.3.2'
   spec.add_dependency 'legion-settings', '>= 1.4.2'
   spec.add_dependency 'legion-transport', '>= 1.4.14'
-  spec.add_dependency 'lex-llm', '>= 0.7.6'
+  # 0.8.0 is the canonical contract cut: base complete funnel with central
+  # canonical enforcement, Canonical::* types, SSOT registry writer path, and
+  # the fleet v3 exact-execution responder the two-file wiring dispatches to.
+  spec.add_dependency 'lex-llm', '>= 0.8.0'
 end

data/lib/legion/extensions/llm/vertex/actors/discovery.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/llm/discovery/actor'
+
+# The base discovery actor only exists inside the daemon (it inherits the
+# LegionIO time-based Every actor). In a standalone load, define nothing.
+return unless defined?(Legion::Extensions::Llm::Discovery::Actor)
+
+module Legion
+  module Extensions
+    module Llm
+      module Vertex
+        module Actor
+          # Vertex discovery actor: an EMPTY subclass of the shared base. The
+          # timer, dispatch, and runner-resolution convention are inherited — this
+          # class redefines nothing. The Vertex-specific work lives in
+          # Vertex::Runners::Discovery, resolved by the base from this
+          # namespace.
+          class Discovery < Legion::Extensions::Llm::Discovery::Actor; end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/llm/vertex/{callable.rb → helpers/callable.rb}

@@ -8,14 +8,27 @@ module Legion
   module Extensions
     module Llm
       module Vertex
-        module Actor
+        module Helpers
           # Callable wrapper for a Vertex AI provider instance. Delegates the
           # fleet dispatch operations to a per-instance Vertex::Provider (real
           # HTTP dispatch; provider/Faraday errors propagate so
           # normalize_dispatch_error classifies them) and implements the
           # `disconnect` and `normalize_dispatch_error(error:)` contracts
           # required by Inventory::CallableHandle and Routing::ProviderOutcome.
-          class VertexCallable
+          # 0.8.0 callable contract: chat/stream_chat take the rehydrated
+          # message array positionally (WorkerExecution dispatch shape) and
+          # the Selection-derived model as a bare String; folded wire params
+          # become Canonical::Params at this boundary (05 O4).
+          class Callable
+            # Keys the base Provider exposes as named kwargs for the
+            # completion operations. Anything else the fleet passes (sampling
+            # scalars, `temperature` — a Canonical::Params member, 05 O4) is
+            # folded into Canonical::Params at the dispatch boundary.
+            COMPLETION_NAMED_KEYS = %i[tools schema thinking tool_prefs headers].freeze
+            # Named kwargs of Vertex's own embed dialect (task_type/title are
+            # Vertex wire spellings); anything else folds into params.
+            EMBED_NAMED_KEYS = %i[dimensions task_type title headers].freeze
+
             attr_reader :provider
 
             def initialize(instance_cfg:, logger:)
@@ -37,20 +50,30 @@ module Legion
 
             # --- Fleet dispatch operations (Fleet::WorkerExecution contract) --
 
-            def chat(messages:, model:, **rest)
-              provider.chat(messages: messages, model: model, **rest)
+            def chat(messages, model:, **rest)
+              # Canonical boundary (N x N law): pipeline dispatch delivers
+              # Canonical::Message objects only. Hash/legacy shapes are the
+              # bypass class — reject loudly, never coerce.
+              provider.enforce_canonical_messages!(messages)
+              named, params = split_fleet_kwargs(rest, COMPLETION_NAMED_KEYS)
+              provider.chat(messages, model: model, params: canonical_params(params), **named)
             end
 
-            def stream_chat(messages:, model:, **rest, &)
-              provider.stream_chat(messages: messages, model: model, **rest, &)
+            def stream_chat(messages, model:, **rest, &)
+              provider.enforce_canonical_messages!(messages)
+              named, params = split_fleet_kwargs(rest, COMPLETION_NAMED_KEYS)
+              provider.stream_chat(messages, model: model, params: canonical_params(params), **named, &)
             end
 
             def embed(text:, model:, **rest)
-              provider.embed(text: text, model: model, **rest)
+              named, params = split_fleet_kwargs(rest, EMBED_NAMED_KEYS)
+              provider.embed(text: text, model: model, params: params, **named)
             end
 
             def count_tokens(messages:, model:, **rest)
-              provider.count_tokens(messages: messages, model: model, **rest)
+              provider.enforce_canonical_messages!(messages)
+              _named, params = split_fleet_kwargs(rest, [])
+              provider.count_tokens(messages: messages, model: model, params: params)
             end
 
             # --- Error normalization ------------------------------------------
@@ -83,6 +106,26 @@ module Legion
 
             private
 
+            # The 0.8.0 completion funnel receives canonical values only
+            # (08 F3): the folded wire params become a Canonical::Params at
+            # the dispatch boundary — temperature is a params member (05 O4),
+            # never a kwarg. A canonical Params already in flight round-trips
+            # through from_hash Data-equal (kit T3/T7); unknown keys fold into
+            # params metadata (04 L5), never dropped or raised.
+            def canonical_params(params)
+              Legion::Extensions::Llm::Canonical::Params.from_hash(params)
+            end
+
+            # Split the fleet's **rest into the provider's named kwargs and a
+            # payload params hash (any passed :params merged with the unknown
+            # keys — sampling scalars, temperature, 0.7.x spellings).
+            def split_fleet_kwargs(rest, named_keys)
+              named = rest.slice(*named_keys)
+              extra = rest.reject { |key, _| named.key?(key) }
+              params = (extra.delete(:params) || {}).to_h.merge(extra)
+              [named, params]
+            end
+
             def classify_client_error(error:)
               case error.response_status
               when 401 then :authentication