lex-llm 0.7.6 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b11032eff9bab4fc8c4ad457cd78fdce95f6ec245a5938dbd6ea987729db4238
-  data.tar.gz: f799901fe6f05201a25237aeafb7779538a995e63e5117e18550935b9e77e12e
+  metadata.gz: 6482361b65a465a6eb683fb1789cd47a6a1a80c709c344eefb57205321e90c12
+  data.tar.gz: b2dd262d310f469fd1c89fa0b00eb1199822397bdb762c17c056b05cbad1b1d6
 SHA512:
-  metadata.gz: d8f610a4c4bb9fdf202c633360c689082f974033e27bdb9bb5c15afa8b609fee313cb36e32109c829b2f6a3613ae64e6859fc962536c804ec3d30f9e47bbc959
-  data.tar.gz: 82b0d2428591452f708a4fbccd9be04c40752cd3b2a5989e0e0df220406a9e6cfe103da82ad9c5d7123d11875bec97f01ad8c81b83e7ca21deac37b4fde03c98
+  metadata.gz: 64cb921e6ccf8361704df0fe4846fb80b3d074ed09b6940f4cff2c2440c8260e36258acda18ed786415d8052a111e33dcd17ad0f1cef1240dd634f14c30f0172
+  data.tar.gz: e2bb88cc4d672f4a11a64cdc91cc922964e67eab8baa85ad3108c40cc269363dc8009684162c70d1f98dbf8d0a0757d0ca8790838eb066ddab59a1edf37cb28d

data/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 0.8.0 - 2026-08-20
+
+**The SSOT v4 contract cut.** This is a complete contract line, not a patch wave:
+Canonical is the only internal language, every authoritative value is created once
+and executed exactly, and one path / one class / one method exists per function.
+The architecture law for the line ships in `RULES.md` at the repository root.
+
+### Added
+- **`RULES.md`** — the 17 architecture laws of the 0.8.x contract line, byte-for-byte
+  at the repo root (G5; mirrored to sibling repos at their next releases).
+- **Fleet protocol v3.** `Fleet::Protocol::VERSION = 3`; exact execution only
+  (marker required — absence is rejected); explicit `protocol_version` (no default
+  fill); one `Fleet::Protocol::REQUIRED_FIELDS` list consumed by both edges;
+  `Fleet::ContractError` for envelope/param/message-shape violations; retryability
+  derived from the `ProviderOutcome` kind table (contract/policy/auth kinds never
+  retry); the response envelope carries the serialized `Canonical::Response` with
+  the G5 thinking exclusion performed exactly once at the responder builder.
+- **Conformance kit.** `spec/legion/extensions/llm/conformance/` now carries the
+  full 09 oracle: T1-T7 shared examples for all 12 canonical types plus the B1-B9
+  (boundary), F1-F7 (fleet), and R1-R5 (registry) shared examples with a kit
+  self-test host.
+- **`Canonical::Thinking::Config`** — one name, a `Data` type (the top-level
+  `ThinkingConfig` constant and its alias are gone).
+- **`Canonical::Message#metadata`** — unknown keys fold into metadata on every
+  canonical type (04 L5); `cache_control` survival through the full JSON wire is
+  conformance-pinned (E01).
+- **Strict argument parser** (`Responses::ToolArguments`) — one strict tool-argument
+  parse for sync and streaming paths; invalid JSON is a contract error, never a
+  fabricated `{}`.
+
+### Changed
+- **Canonical strictification (04 L1-L10).** No nil-returning factories (typed
+  `ArgumentError` naming type, member, and offending class); no rescue-and-repair;
+  no silent drops; canonical keys only (provider-dialect aliases moved to the
+  translator edges, O03a); declared enums validated in both factories; `build` and
+  `from_hash` share one normalization path per member; uniform `to_h`/`as_json`/
+  `to_json` serialization; G20d (chunk produce-strict / consume-unknown pass-through)
+  is stated law.
+- **Provider funnel (05/08).** `complete` enforces canonical messages centrally
+  (F2); the `temperature:` kwarg is deleted (temperature lives only in
+  `Canonical::Params`, O4); positional `messages` on the callable contract; the
+  provider-object fleet dispatch topology is deleted (exact registry dispatch only);
+  the legacy offering production path is replaced by the `Registry.snapshot` read
+  path (07 C5); one `ensure_configured!` (the Connection duplicate is deleted); one
+  health classifier; `normalize_dispatch_error` reads the shared kind table on
+  `Routing::ProviderOutcome`; silent rescues now log.
+- **Streaming (02 FL13 / 10 U1-U3).** The streaming path produces
+  `Canonical::Chunk` / `Canonical::Response` through the shared `ThinkingExtractor`
+  segment core and the strict tool-argument parser, preserving the wire
+  index-first / recency-fallback tool-call correlation law.
+- **`FleetLane` queue defaults** come from the one settings home
+  (`Llm.default_settings`, `consumer_ack_timeout_ms: 90_000`); the downgraded
+  `CredentialSources` paths fail closed (O11).
+- **`Routing::Selection` weight validation** is structural only — a zero component
+  (operator disable) is accepted, matching `RecordSupport` (U4).
+
+### Removed
+- **The legacy type set:** `Llm::Message`, `Llm::Chunk`, `Llm::Tokens`,
+  `Llm::Thinking` (+ `Thinking::Config`), `Llm::ToolCall`, `Llm::Content`
+  (+ `Content::Raw`), `Llm::Attachment`, the `Responses::ChatResponse` /
+  `StreamChunk` / `EmbeddingResponse` wrapper family, and `to_internal_h`.
+- **The provider-native facade** (O12): `Llm.chat/context/embed/moderate/paint/
+  transcribe/models/providers` entry points, `Chat`, `Agent`, `Context` — zero
+  callers in any repo; capability is preserved through the provider base +
+  canonical pipeline + fleet.
+- **Legacy offering/lane surface:** `Routing::ModelOffering`, `Routing::OfferingRegistry`,
+  `Routing::LaneKey`, `Inventory::ScopedRefresher` (+ `LegacyCoordinatorAdapter` —
+  the lex-llm -> legion-llm reverse dependency is gone), the `Llm::Types` alias
+  module, `AutoRegistration#discover_instances`/`#provider_aliases`, the
+  `UnsupportedCapabilityError` compat alias, `Llm::Aliases`,
+  `Taxonomies::OPERATION_ALIASES`/`OPERATION_TO_LANE_TYPE`/`CIRCUIT_STATES`/
+  `HEALTH_KEYS`, `Message.wrap`, `Message#to_provider_hash`, `AmbiguousLegacyOfferingError`,
+  and the class-level `model_policy`/`resolve_policy_value` policy cascade.
+
+## 0.7.7 - 2026-08-19
+
+
+### Added
+- **`Canonical::Message` carries `cache_control`.** Prompt-cache breakpoints are a first-class canonical member (build/from_hash/to_h and the fleet JSON round-trip preserve it) instead of being dropped by member projection.
+
+### Changed
+- **Fleet worker rehydrates wire messages to canonical objects.** `Fleet::WorkerExecution` rebuilds `params[:messages]` into `Canonical::Message` at the wire boundary for chat, stream, and count_tokens dispatch (exact and local-provider paths), so callables receive canonical input only. Non-Hash wire entries raise `ExactOfferingMismatchError`.
+
+### Fixed
+- **Dispatch-boundary contract helper.** `Provider#enforce_canonical_messages!` is the shared loud-reject contract for provider callables: non-canonical message shapes raise `ArgumentError` instead of being coerced or tolerated. `Provider#count_tokens` enforces it and reads canonical content, removing the hash fallback.
+- **Fleet specs assert the canonical boundary.** Worker/responder spec doubles read `.content` off `Canonical::Message` (wire rehydration delivers objects, not hashes).
+
 ## 0.7.6 - 2026-08-19
 
 ### Added

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/lib/legion/extensions/llm/auto_registration.rb

@@ -10,20 +10,11 @@ module Legion
       # Prerequisites on the extending module:
       #   - `PROVIDER_FAMILY` constant (Symbol, e.g. :ollama)
       #   - `provider_class` singleton method returning the Provider subclass
-      # DEPRECATED (Phase 4 removal): discover_instances/provider_aliases are kept
-      # for old consumers; no new registration side effect is added here. Migrated
-      # provider actors use Inventory::Publisher directly.
+      #
+      # The legacy discover_instances/provider_aliases defaults are deleted
+      # (Phase 4): providers define their own instance discovery, and
+      # publication goes through Inventory::Publisher directly.
       module AutoRegistration
-        # Override in each provider.  Returns { instance_id => config_hash }.
-        def discover_instances
-          {}
-        end
-
-        # Optional provider-family aliases that legion-llm should register
-        # against the same discovered provider instances.
-        def provider_aliases
-          []
-        end
       end
     end
   end

data/lib/legion/extensions/llm/canonical/chunk.rb

@@ -7,24 +7,45 @@ module Legion
       module Canonical
         # Canonical streaming chunk with full lifecycle support.
         # Per R4: block_index/item_id/signature lifecycle, multi-tool-call deltas.
-        # Per G20d: strict on produce, ignore-unknown on consume.
+        # Per G20d (04 §11, stated law): strict on produce — the named factories
+        # and the generic build validate type against CHUNK_TYPES; lenient on
+        # consume — from_hash accepts any type symbol and passes it through. # -- required for Data.define block scope
         Chunk = ::Data.define(
           :request_id, :conversation_id, :exchange_id,
           :index, :type, :block_index,
           :item_id, :delta, :tool_call, :signature,
           :usage, :stop_reason, :metadata, :timestamp
         ) do
+          # Generic produce path — the only way to construct an arbitrary-type
+          # chunk; type is validated against CHUNK_TYPES (G20d).
+          def self.build(
+            type:, request_id: nil, conversation_id: nil, exchange_id: nil,
+            index: nil, block_index: nil, item_id: nil,
+            delta: nil, tool_call: nil, signature: nil,
+            usage: nil, stop_reason: nil, metadata: {}, timestamp: nil
+          )
+            type_sym = type.is_a?(::String) ? type.to_sym : type
+            Strict.enum!(type_sym, self::CHUNK_TYPES, self::BUILD_SITE, :type)
+            new(
+              request_id:, conversation_id:, exchange_id:,
+              index:, type: type_sym, block_index:,
+              item_id:, delta:,
+              tool_call: normalize_tool_call!(tool_call, self::BUILD_SITE),
+              signature:,
+              usage: normalize_usage!(usage, self::BUILD_SITE),
+              stop_reason: stop_reason&.to_sym,
+              metadata: Strict.metadata!(metadata, self::BUILD_SITE),
+              timestamp: timestamp || ::Time.now
+            )
+          end
+
           # Build a text delta chunk.
           def self.text_delta(delta:, request_id:, conversation_id: nil, exchange_id: nil,
                               index: 0, block_index: nil, item_id: nil,
                               stop_reason: nil, usage: nil)
-            new(
-              type: :text_delta, delta: delta, index: index,
-              request_id: request_id, conversation_id: conversation_id,
-              exchange_id: exchange_id, block_index: block_index,
-              item_id: item_id, tool_call: nil, signature: nil,
-              usage: usage, stop_reason: stop_reason, metadata: {},
-              timestamp: ::Time.now
+            build(
+              type: :text_delta, delta:, request_id:, conversation_id:, exchange_id:,
+              index:, block_index:, item_id:, stop_reason:, usage:
             )
           end
 
@@ -32,117 +53,93 @@ module Legion
           def self.thinking_delta(delta:, request_id:, conversation_id: nil, exchange_id: nil,
                                   index: 0, block_index: nil, item_id: nil, signature: nil,
                                   stop_reason: nil, usage: nil)
-            new(
-              type: :thinking_delta, delta: delta, index: index,
-              request_id: request_id, conversation_id: conversation_id,
-              exchange_id: exchange_id, block_index: block_index,
-              item_id: item_id, tool_call: nil, signature: signature,
-              usage: usage, stop_reason: stop_reason, metadata: {},
-              timestamp: ::Time.now
+            build(
+              type: :thinking_delta, delta:, request_id:, conversation_id:, exchange_id:,
+              index:, block_index:, item_id:, signature:, stop_reason:, usage:
             )
           end
 
-          # Build a tool_call_delta chunk (supports multiple in-flight tool calls via tool_call.id).
+          # Build a tool_call_delta chunk (supports multiple in-flight tool calls
+          # via the fragment's id/index). tool_call is the delta fragment:
+          # { id:, name:, arguments: <String fragment>, index:, signature: }.
           def self.tool_call_delta(tool_call:, request_id:, conversation_id: nil, exchange_id: nil,
                                    index: 0, block_index: nil, item_id: nil,
                                    stop_reason: nil, usage: nil)
-            new(
-              type: :tool_call_delta, index: index,
-              request_id: request_id, conversation_id: conversation_id,
-              exchange_id: exchange_id, block_index: block_index,
-              item_id: item_id, delta: nil, tool_call: tool_call, signature: nil,
-              usage: usage, stop_reason: stop_reason, metadata: {},
-              timestamp: ::Time.now
+            build(
+              type: :tool_call_delta, tool_call:, request_id:, conversation_id:, exchange_id:,
+              index:, block_index:, item_id:, stop_reason:, usage:
             )
           end
 
           # Build a usage chunk.
           def self.usage_chunk(usage:, request_id:, conversation_id: nil, exchange_id: nil)
-            new(
-              type: :usage, request_id: request_id,
-              conversation_id: conversation_id, exchange_id: exchange_id,
-              index: nil, block_index: nil, item_id: nil,
-              delta: nil, tool_call: nil, signature: nil,
-              usage: usage, stop_reason: nil, metadata: {},
-              timestamp: ::Time.now
-            )
+            build(type: :usage, request_id:, conversation_id:, exchange_id:, usage:)
           end
 
           # Build a done chunk.
           def self.done(request_id:, usage: nil, stop_reason: nil, conversation_id: nil, exchange_id: nil)
-            new(
-              type: :done, request_id: request_id,
-              conversation_id: conversation_id, exchange_id: exchange_id,
-              index: nil, block_index: nil, item_id: nil,
-              delta: nil, tool_call: nil, signature: nil,
-              usage: usage, stop_reason: stop_reason, metadata: {},
-              timestamp: ::Time.now
-            )
+            build(type: :done, request_id:, usage:, stop_reason:, conversation_id:, exchange_id:)
           end
 
           # Build an error chunk.
-          def self.error_chunk(error:, request_id:, conversation_id: nil, exchange_id: nil, metadata: nil)
-            new(
-              type: :error, request_id: request_id,
-              conversation_id: conversation_id, exchange_id: exchange_id,
-              index: nil, block_index: nil, item_id: nil,
-              delta: nil, tool_call: nil, signature: nil,
-              usage: nil, stop_reason: :error,
-              metadata: (metadata || {}).merge(error: error),
-              timestamp: ::Time.now
+          def self.error_chunk(error:, request_id:, conversation_id: nil, exchange_id: nil, metadata: {})
+            build(
+              type: :error, request_id:, conversation_id:, exchange_id:,
+              stop_reason: :error, metadata: metadata.merge(error:)
             )
           end
 
-          # Build from a Hash (raw provider response or deserialized wire payload).
-          # Per G20d: ignore-unknown on consume — unknown chunk types are passed through.
-          def self.from_hash(source)
-            return nil if source.nil?
-
-            h = source.transform_keys(&:to_sym)
+          def self.shape_symbol!(value, site, member)
+            return nil if value.nil?
+            return value.to_sym if value.is_a?(::String) || value.is_a?(::Symbol)
 
-            # Normalize type
-            type_raw = h.delete(:type)
-            type_sym = type_raw&.to_sym if type_raw
+            raise ArgumentError, "#{site}: #{member} expected String or Symbol, got #{value.class}"
+          end
 
-            # Normalize nested objects
-            tool_call_raw = h.delete(:tool_call)
-            h[:tool_call] = if tool_call_raw.is_a?(ToolCall)
-                              tool_call_raw
-                            elsif tool_call_raw.is_a?(Hash)
-                              ToolCall.from_hash(tool_call_raw)
-                            end
+          # Build from a Hash (raw provider response or deserialized wire payload).
+          # Per G20d: ignore-unknown on consume — unknown chunk types pass through.
+          def self.from_hash(source)
+            Strict.require_hash!(source, self::FROM_HASH_SITE)
+            hash = Strict.symbolize_keys(source)
+            metadata = Strict.fold_unknowns!(self, self::FROM_HASH_SITE, hash)
+            type_raw = hash.delete(:type)
+            tool_call = normalize_tool_call!(hash.delete(:tool_call), self::FROM_HASH_SITE)
+            usage = normalize_usage!(hash.delete(:usage), self::FROM_HASH_SITE)
+            stop_reason_raw = hash.delete(:stop_reason)
+            timestamp = hash.delete(:timestamp)
+            # Remaining keys are all members; pass through with consume defaults.
+            new(
+              request_id: hash[:request_id],
+              conversation_id: hash[:conversation_id],
+              exchange_id: hash[:exchange_id],
+              index: hash[:index],
+              type: type_raw&.to_sym,
+              block_index: hash[:block_index],
+              item_id: hash[:item_id],
+              delta: hash[:delta],
+              tool_call:,
+              signature: hash[:signature],
+              usage:,
+              stop_reason: stop_reason_raw&.to_sym,
+              metadata:,
+              timestamp: timestamp || ::Time.now
+            )
+          end
 
-            usage_raw = h.delete(:usage)
-            h[:usage] = if usage_raw.is_a?(Usage)
-                          usage_raw
-                        elsif usage_raw.is_a?(Hash)
-                          Usage.from_hash(usage_raw)
-                        end
+          # tool_call member: the delta fragment (Hash) or a full ToolCall; nil allowed.
+          def self.normalize_tool_call!(tool_call, site)
+            return nil if tool_call.nil?
+            return tool_call if tool_call.is_a?(::Hash) || tool_call.is_a?(ToolCall)
 
-            # Normalize stop_reason
-            stop_reason_raw = h.delete(:stop_reason) || h.delete(:finish_reason)
-            h[:stop_reason] = stop_reason_raw&.to_sym if stop_reason_raw
+            Strict.expect_type!(tool_call, [::Hash, ToolCall], site, :tool_call)
+          end
 
-            # Ensure metadata is a Hash
-            h[:metadata] = h[:metadata] || {}
+          def self.normalize_usage!(usage, site)
+            return nil if usage.nil?
+            return usage if usage.is_a?(Usage)
 
-            # Provide defaults for missing fields
-            new(
-              request_id: h[:request_id],
-              conversation_id: h[:conversation_id],
-              exchange_id: h[:exchange_id],
-              index: h[:index],
-              type: type_sym,
-              block_index: h[:block_index],
-              item_id: h[:item_id],
-              delta: h[:delta],
-              tool_call: h[:tool_call],
-              signature: h[:signature],
-              usage: h[:usage],
-              stop_reason: h[:stop_reason],
-              metadata: h[:metadata],
-              timestamp: h[:timestamp] || ::Time.now
-            )
+            Strict.expect_type!(usage, [::Hash], site, :usage)
+            Usage.from_hash(usage)
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -186,9 +183,26 @@ module Legion
           def content?
             %i[text_delta thinking_delta].include?(type)
           end
+
+          # H1: the single strict constructor. Member shapes are validated
+          # (type/stop_reason as String|Symbol, tool_call/usage through the
+          # normalizers, metadata as a Hash). Per G20d the TYPE is only
+          # shape-checked here — the produce-side enum pin stays in build,
+          # and from_hash (consume) passes unknown types through.
+          Strict.install_strict_new!(self) do |values, site|
+            values[:type] = shape_symbol!(values[:type], site, :type)
+            values[:stop_reason] = shape_symbol!(values[:stop_reason], site, :stop_reason)
+            values[:tool_call] = normalize_tool_call!(values[:tool_call], site)
+            values[:usage] = normalize_usage!(values[:usage], site)
+            values[:metadata] = Strict.metadata!(values[:metadata], site)
+            values
+          end
         end
 
         Chunk::CHUNK_TYPES = %i[text_delta thinking_delta tool_call_delta usage done error].freeze
+        Chunk::BUILD_SITE = 'Canonical::Chunk.build'
+        Chunk::FROM_HASH_SITE = 'Canonical::Chunk.from_hash'
+        Chunk::NEW_SITE = 'Canonical::Chunk.new'
       end
     end
   end