runtype 0.5.0 → 0.11.1

data/lib/runtype/agent_ensure.rb

@@ -36,12 +36,22 @@ module Runtype
     #   `deploy:`: `"publish"` also re-aims the `live` alias; default `"none"`.
     # @param deploy [Hash, String, Symbol, nil] activates the saved version at a
     #   release alias, e.g. `{ alias: "pr-482" }` or the bare `"live"`. Omit
-    #   both `release:` and `deploy:` to save without activating.
+    #   both `release:` and `deploy:` to save without activating. `bindings:`
+    #   (`{ "API_URL" => "https://staging..." }`) replaces the alias's
+    #   per-alias secret overrides, as in the TypeScript SDK.
     # @param expected_remote_hash [String, nil] binds a dry run to its apply:
     #   the write proceeds only if the remote still hashes to this value.
     # @param version [Hash, nil] provenance recorded on the version row this
     #   converge appends, e.g. `{ label: "a1b2c3d", notes: "CI run 4821" }`.
     #   Omit to keep the default `"sdk-ensure"` label and the server's notes.
+    # @param skills [Array<Hash>, nil] the complete set of skills bound to the
+    #   agent, in load order, e.g. `[{ name: "refund-policy", version: 3 }]`.
+    #   `version:` pins a skill versionNumber; omit it to follow the published
+    #   version. Bound skills absent here are unbound; `nil` leaves them alone.
+    # @param capabilities [Array<Hash>, nil] the complete set of capabilities in
+    #   display order, e.g. `[{ toolName: "lookup_order", flow: "Order Lookup" }]`.
+    #   Each names exactly one `flow:`, `agent:` or `tool:` source by name.
+    #   Capabilities absent here are removed; `nil` leaves them alone.
     # @param request_options [Hash] see {Runtype::Client#dispatch}.
     # @return [Hash] `{"result" => "unchanged"|"created"|"updated", "agentId",
     #   "versionId", "contentHash"}`, or for a dry run `{"result" => "plan",
@@ -50,11 +60,13 @@ module Runtype
     # @raise [Runtype::EnsureConflictError] on a 409 (`external_modification`
     #   or `remote_changed`).
     # @raise [Runtype::DriftError] with `expect_no_changes:` when the plan is
-    #   not `"none"`.
+    #   not `"none"`, would change a skill binding or, with `release:` or
+    #   `deploy:`, would move the alias or change its binding names.
     # @raise [ArgumentError] when both `release:` and `deploy:` are given, or
     #   when `version:` carries a key other than `label:` and `notes:`.
     def ensure_agent(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
-                     deploy: nil, expected_remote_hash: nil, version: nil, request_options: {})
+                     deploy: nil, expected_remote_hash: nil, version: nil, skills: nil, capabilities: nil,
+                     request_options: {})
       raise ArgumentError, RELEASE_DEPLOY_CONFLICT_MESSAGE if release && deploy
 
       definition = Runtype::AgentDefinition.from(definition)
@@ -63,7 +75,9 @@ module Runtype
         release: release&.to_s,
         deploy: deploy_intent(deploy),
         expectedRemoteHash: expected_remote_hash,
-        version: version_metadata(version)
+        version: version_metadata(version),
+        skills: skills&.map(&:to_h),
+        capabilities: capabilities&.map(&:to_h)
       }.compact
 
       if dry_run || expect_no_changes
@@ -73,7 +87,7 @@ module Runtype
         unless plan["result"] == "plan"
           raise Runtype::Error, "Expected a plan result from dryRun, got #{plan["result"].inspect}"
         end
-        raise Runtype::DriftError.new(plan, name: definition.name) if expect_no_changes && plan["changes"] != "none"
+        raise Runtype::DriftError.new(plan, name: definition.name) if expect_no_changes && drifted?(plan, passthrough)
 
         return plan
       end
@@ -107,13 +121,28 @@ module Runtype
 
     private
 
+    # Whether a dry-run plan fails the drift gate: content or skill-binding
+    # changes, or, when the converge asked to activate an alias, a pointer move
+    # or a binding-name change at that alias.
+    #
+    # @param plan [Hash]
+    # @param passthrough [Hash] the options this converge sends.
+    # @return [Boolean]
+    def drifted?(plan, passthrough)
+      return true if plan["changes"] != "none" || Runtype::DriftError.skill_changes(plan).any?
+
+      deploy_requested = passthrough.key?(:deploy) || passthrough[:release] == "publish"
+      deploy_requested && Runtype::DriftError.deployment_changes(plan).any?
+    end
+
     # Normalizes the two accepted spellings of `deploy:` into the wire shape.
-    # A bare String or Symbol names the alias; a Hash may spell its key either
+    # A bare String or Symbol names the alias; a Hash may spell its keys either
     # way. The alias name itself is never resolved client-side.
     #
     # @param deploy [Hash, String, Symbol, nil]
-    # @return [Hash, nil] `{ alias: "<name>" }`, or nil when nothing was asked.
-    # @raise [ArgumentError] when a Hash carries no alias name.
+    # @return [Hash, nil] `{ alias: "<name>", bindings: {...}? }`, or nil when nothing was asked.
+    # @raise [ArgumentError] when a Hash carries no alias name, or a supplied
+    #   `bindings:` (nil included) is not a Hash of String names to String values.
     def deploy_intent(deploy)
       return nil if deploy.nil?
       return { alias: deploy.to_s } unless deploy.is_a?(Hash)
@@ -121,7 +150,33 @@ module Runtype
       name = deploy[:alias] || deploy["alias"]
       raise ArgumentError, "deploy: needs an alias name, e.g. deploy: { alias: \"live\" }." if name.nil?
 
-      { alias: name.to_s }
+      return { alias: name.to_s } unless deploy.key?(:bindings) || deploy.key?("bindings")
+
+      bindings = deploy.key?(:bindings) ? deploy[:bindings] : deploy["bindings"]
+      { alias: name.to_s, bindings: deploy_bindings(bindings) }
+    end
+
+    # Validates `deploy: { bindings: }`, the per-alias `{{secret:NAME}}`
+    # overrides. Names may be Symbols; values must already be Strings so a
+    # stray nil or number fails here rather than binding its `to_s`.
+    #
+    # @param bindings [Hash]
+    # @return [Hash{String => String}]
+    # @raise [ArgumentError] on a non-Hash or a non-String value.
+    def deploy_bindings(bindings)
+      unless bindings.is_a?(Hash)
+        raise ArgumentError,
+              "deploy: bindings: needs a Hash of secret names to values, e.g. { \"API_URL\" => \"https://...\" }."
+      end
+
+      bindings.each_with_object({}) do |(key, value), acc|
+        unless (key.is_a?(String) || key.is_a?(Symbol)) && value.is_a?(String)
+          raise ArgumentError,
+                "deploy: bindings: maps String names to String values; got #{key.inspect} => #{value.class}."
+        end
+
+        acc[key.to_s] = value
+      end
     end
 
     # Normalizes `version:` into the wire shape. Keys may be Symbols or Strings;

data/lib/runtype/client.rb

@@ -26,6 +26,7 @@ module Runtype
   # clients with different keys or base URLs can coexist in one process.
   class Client
     include Runtype::AgentEnsure
+    include Runtype::ConfigEnsure
     include Runtype::AgentReleaseAliases
     include Runtype::LocalToolRunner
 

data/lib/runtype/config_ensure.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Runtype
+  # Config-as-code on {Runtype::Client} for skills, flows, tools, surfaces,
+  # products and evals: the same hash-first ensure protocol as
+  # {AgentEnsure#ensure_agent}, mirroring the TypeScript SDK's `*-ensure.ts`
+  # modules option for option. Protocol: `docs/adr/0003-agent-config-as-code-ensure.md`.
+  #
+  # Definitions are plain Hashes in wire shape (camelCase keys, Symbol or
+  # String). Every converge probes with the content hash, ships the full
+  # definition only on `definitionRequired`, memoizes the server's hash per
+  # client, raises {Runtype::EnsureConflictError} on the protocol's 409 and
+  # {Runtype::DriftError} under `expect_no_changes:`.
+  module ConfigEnsure
+    Kind = Struct.new(:label, :pull_hint, :ensure_hint, :hasher, :drift, keyword_init: true)
+
+    SKILL = Kind.new(label: "Skill", pull_hint: "client.pull_skill(name)", ensure_hint: "ensure_skill",
+                     hasher: ContentHash.method(:skill), drift: true)
+    FLOW = Kind.new(label: "Flow", pull_hint: "client.pull_flow(name)", ensure_hint: "ensure_flow",
+                    hasher: ->(definition) { ContentHash.flow(definition["steps"] || []) }, drift: true)
+    TOOL = Kind.new(label: "Tool", pull_hint: "client.pull_tool(name)", ensure_hint: "ensure_tool",
+                    hasher: ContentHash.method(:tool), drift: true)
+    SURFACE = Kind.new(label: "Surface", pull_hint: "client.pull_surface(product_id, name)",
+                       ensure_hint: "ensure_surface", hasher: ContentHash.method(:surface), drift: true)
+    PRODUCT = Kind.new(label: "Product", pull_hint: "client.pull_product(name)", ensure_hint: "ensure_product",
+                       hasher: ContentHash.method(:product), drift: true)
+    EVAL = Kind.new(label: "Eval", pull_hint: "client.pull_eval(name)", ensure_hint: "ensure_eval",
+                    hasher: ContentHash.method(:eval_suite), drift: false)
+
+    # Converges `{ name:, manifest: { frontmatter:, runtype:?, body: } }`. Every
+    # change appends an immutable version.
+    #
+    # @param definition [Hash]
+    # @param dry_run [Boolean] plan without writing (the CI drift gate).
+    # @param expect_no_changes [Boolean] implies `dry_run`; raises {Runtype::DriftError} unless the plan is `"none"`.
+    # @param on_conflict [String, Symbol, nil] `"error"` (default) or `"overwrite"`.
+    # @param release [String, Symbol, nil] `"publish"` also re-aims the published-version pointer.
+    # @param expected_remote_hash [String, nil] the write proceeds only if the remote still hashes to this.
+    # @param request_options [Hash] see {Runtype::Client#dispatch}.
+    # @return [Hash] `{"result", "skillId", "versionId", "contentHash"}`, or the dry-run plan.
+    # @raise [Runtype::EnsureConflictError] on the protocol's 409.
+    # @raise [Runtype::DriftError] with `expect_no_changes:` when the plan is not `"none"`.
+    def ensure_skill(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
+                     expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, release: release&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(SKILL, "v1/skills/ensure", wire, skill_wire(wire), options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"skillId", "definition", "contentHash", "lastModifiedSource", "updatedAt", "versionId"}`.
+    def pull_skill(name, request_options: {})
+      get_json("v1/skills/pull", { name: name }, request_options)
+    end
+
+    # Converges `{ name:, steps: [...], evals:? }`. Inline `evals` are not part
+    # of the flow wire: each converges through {#ensure_eval} after the flow and
+    # is reported as `result["evals"]`; a dry run skips them.
+    #
+    # @param version [Hash, nil] provenance for the version row, `{ label:, notes: }`.
+    # @return [Hash] `{"result", "flowId", "versionId", "contentHash", "evals"?}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_flow(definition, dry_run: false, expect_no_changes: false, on_conflict: nil, release: nil,
+                    expected_remote_hash: nil, version: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, release: release&.to_s, expectedRemoteHash: expected_remote_hash,
+                  version: version_metadata(version) }
+      flow_wire = { "name" => wire["name"], "steps" => wire["steps"] || [] }
+      result = converge_config(FLOW, "v1/flows/ensure", wire, flow_wire, options.compact,
+                               dry_run: dry_run, expect_no_changes: expect_no_changes,
+                               request_options: request_options)
+      inline_evals = Array(wire["evals"])
+      return result if result["result"] == "plan" || inline_evals.empty?
+
+      result.merge("evals" => inline_evals.map { |suite| ensure_eval(suite, request_options: request_options) })
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"flowId", "definition", "contentHash", "lastModifiedSource", "updatedAt", "versionId"}`.
+    def pull_flow(name, request_options: {})
+      get_json("v1/flows/pull", { name: name }, request_options)
+    end
+
+    # Converges `{ name:, description:, toolType:, parametersSchema:, config: }`. Never deletes.
+    #
+    # @return [Hash] `{"result", "toolId", "contentHash"}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_tool(definition, dry_run: false, expect_no_changes: false, on_conflict: nil,
+                    expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(TOOL, "v1/tools/ensure", wire, wire, options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"toolId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_tool(name, request_options: {})
+      get_json("v1/tools/pull", { name: name }, request_options)
+    end
+
+    # Converges `{ name:, type:, behavior:?, inbound:?, outbound:?, status:? }`
+    # as a surface of `product_id`; identity is the name within that product.
+    #
+    # @param product_id [String]
+    # @return [Hash] `{"result", "surfaceId", "contentHash"}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_surface(product_id, definition, dry_run: false, expect_no_changes: false, on_conflict: nil,
+                       expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(SURFACE, surface_path(product_id, "ensure"), wire, wire, options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options,
+                      memo_scope: product_id.to_s,
+                      probe_first: !(wire.key?("inbound") || wire.key?("outbound")))
+    end
+
+    # @param product_id [String]
+    # @param name [String]
+    # @return [Hash] `{"surfaceId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_surface(product_id, name, request_options: {})
+      get_json(surface_path(product_id, "pull"), { name: name }, request_options)
+    end
+
+    # Converges the product row `{ name:, description:?, icon:?, spec:? }`.
+    #
+    # @return [Hash] `{"result", "productId", "contentHash"}`, or the dry-run plan.
+    # @see #ensure_skill for the shared options and errors.
+    def ensure_product(definition, dry_run: false, expect_no_changes: false, on_conflict: nil,
+                       expected_remote_hash: nil, request_options: {})
+      wire = config_wire(definition)
+      options = { onConflict: on_conflict&.to_s, expectedRemoteHash: expected_remote_hash }
+      converge_config(PRODUCT, "v1/products/ensure", wire, wire, options.compact,
+                      dry_run: dry_run, expect_no_changes: expect_no_changes, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"productId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_product(name, request_options: {})
+      get_json("v1/products/pull", { name: name }, request_options)
+    end
+
+    # Converges a whole Full Product Object; the server fans out per entity.
+    # Ships the full FPO (no hash probe). Non-atomic: inspect `"hasFailures"`
+    # and `"entities"` and re-run to self-heal.
+    #
+    # @param fpo [Hash]
+    # @param prune [Boolean] remove product-scoped capabilities and surfaces absent from the FPO.
+    # @return [Hash] `{"result", "productId", "contentHash", "entities", "hasFailures"}`.
+    def ensure_fpo(fpo, dry_run: false, on_conflict: nil, prune: false, request_options: {})
+      body = { fpo: fpo }
+      body[:dryRun] = true if dry_run
+      body[:onConflict] = on_conflict.to_s if on_conflict
+      body[:prune] = true if prune
+      config_ensure_request("v1/products/ensure-fpo", body, request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"productId", "fpo", "contentHash", "warnings"?}`.
+    def pull_fpo(name, request_options: {})
+      get_json("v1/products/pull-fpo", { name: name }, request_options)
+    end
+
+    # Converges an eval suite `{ name:, target:, cases:, virtual:, ... }`
+    # (cases carry their merged graders in `expect`). Never executes it.
+    #
+    # @return [Hash] `{"result", "suiteId", "contentHash"}`.
+    # @raise [ArgumentError] for a virtual suite, which has nothing durable to converge.
+    def ensure_eval(definition, request_options: {})
+      wire = config_wire(definition)
+      if wire["virtual"]
+        raise ArgumentError, "Cannot ensure a virtual eval: virtual evals are ephemeral (nothing is persisted to " \
+                             "converge). Remove virtual: true to converge a durable suite, or run it directly."
+      end
+
+      converge_config(EVAL, "v1/eval/ensure", wire, wire, {}, request_options: request_options)
+    end
+
+    # @param name [String]
+    # @return [Hash] `{"suiteId", "definition", "contentHash", "lastModifiedSource", "updatedAt"}`.
+    def pull_eval(name, request_options: {})
+      get_json("v1/eval/pull", { name: name }, request_options)
+    end
+
+    private
+
+    # Round-trips through JSON so Symbol keys and values hash exactly as they will be sent.
+    def config_wire(definition)
+      JSON.parse(JSON.generate(definition.to_h))
+    end
+
+    def skill_wire(wire)
+      manifest = wire["manifest"].is_a?(Hash) ? wire["manifest"] : {}
+      frontmatter = (manifest["frontmatter"] || {}).dup
+      runtype_block = flatten_unknown_extensions(manifest["runtype"])
+      frontmatter["runtype"] = runtype_block unless runtype_block.empty?
+      { "frontmatter" => frontmatter, "body" => manifest["body"] || "" }
+    end
+
+    # Spreads a pulled `unknownExtensions` back to top-level `runtype` keys, as SKILL.md stores them.
+    def flatten_unknown_extensions(runtype_block)
+      return {} unless runtype_block.is_a?(Hash)
+
+      extensions = runtype_block["unknownExtensions"]
+      flattened = runtype_block.except("unknownExtensions")
+      extensions.is_a?(Hash) ? flattened.merge(extensions) : flattened
+    end
+
+    def surface_path(product_id, action)
+      "v1/products/#{URI.encode_uri_component(product_id.to_s)}/surfaces/#{action}"
+    end
+
+    def converge_config(kind, path, wire, sent, options, request_options:, dry_run: false,
+                        expect_no_changes: false, memo_scope: "", probe_first: true)
+      name = wire["name"]
+      raise ArgumentError, "#{kind.label} ensure requires a definition with a non-empty name" unless
+        name.is_a?(String) && !name.empty?
+
+      if dry_run || expect_no_changes
+        plan = config_ensure_request(path, { name: name, definition: sent, dryRun: true, **options },
+                                     request_options)
+        return check_config_plan(kind, plan, name, expect_no_changes)
+      end
+
+      local_hash = kind.hasher.call(wire)
+      memo_key = "#{memo_scope}\0#{name}\0#{local_hash}"
+      probe = { "result" => "definitionRequired" }
+      if probe_first
+        probe = config_ensure_request(
+          path, { name: name, contentHash: config_ensure_memo[memo_key] || local_hash, **options },
+          request_options
+        )
+      end
+      if probe["result"] == "definitionRequired"
+        probe = config_ensure_request(path, { name: name, definition: sent, **options }, request_options)
+        if probe["result"] == "definitionRequired"
+          raise Runtype::Error, "Server reported definitionRequired for a full-definition request"
+        end
+      end
+      config_ensure_memo[memo_key] = probe["contentHash"] if probe["result"] != "plan" && probe["contentHash"]
+      probe
+    end
+
+    def check_config_plan(kind, plan, name, expect_no_changes)
+      raise Runtype::Error, "Expected a plan result from dryRun, got #{plan["result"].inspect}" unless
+        plan["result"] == "plan"
+      if expect_no_changes && kind.drift && (plan["changes"] != "none" || plan["publishPending"] == true)
+        raise Runtype::DriftError.new(plan, name: name, entity: kind.label, pull_hint: kind.pull_hint,
+                                            ensure_hint: kind.ensure_hint)
+      end
+
+      plan
+    end
+
+    # @return [Hash{String => String}] `scope\0name\0localHash` => server hash.
+    def config_ensure_memo
+      @config_ensure_memo ||= {}
+    end
+
+    def config_ensure_request(path, body, request_options)
+      post_json(path, body, request_options)
+    rescue Runtype::APIStatusError => e
+      raise Runtype::EnsureConflictError.from_status_error(e) if Runtype::EnsureConflictError.protocol_conflict?(e)
+
+      raise
+    end
+  end
+end

data/lib/runtype/content_hash.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Runtype
+  # Canonical content hashes for the config-as-code ensure surfaces other than
+  # agents (see {AgentDefinition.content_hash_for}). Each is a wire contract
+  # with the API and the TypeScript SDK, pinned by the corpora under
+  # `packages/shared/test-fixtures/*-content-hash/cases.json`. A key absent
+  # from a Hash plays JavaScript's `undefined` (dropped); `nil` plays `null`.
+  module ContentHash
+    MAX_ARRAY_INDEX = 4_294_967_294
+    FPO_OPTIONAL_SECTIONS = %w[records schedules secrets evals skills].freeze
+    SERVER_SET_STACK_FIELDS = %w[detected declared hiddenAt].freeze
+
+    module_function
+
+    # @param steps [Array<Hash>] a flow's steps.
+    # @return [String] SHA-256 hex over the canonical step list.
+    def flow(steps)
+      sha256(normalize_flow_steps(steps))
+    end
+
+    # @param steps [Array<Hash>]
+    # @return [Array<Hash>] the canonical steps, sorted by `order`.
+    def normalize_flow_steps(steps)
+      Array(steps).each_with_index
+                  .map { |step, index| legacy_flow_step_identity(stringify(step), index) }
+                  .each_with_index
+                  .sort_by { |step, index| [step_order(step), index] }
+                  .map { |step, _index| normalize_flow_step(step) }
+    end
+
+    # @param definition [Hash] `{ name:, manifest: { frontmatter:, runtype:, body: } }`.
+    # @return [String] SHA-256 hex; the frontmatter name is identity, not content.
+    def skill(definition)
+      manifest = plain(stringify(definition)["manifest"])
+      frontmatter = plain(manifest["frontmatter"]).except("name")
+      runtype_block = manifest["runtype"]
+      body = manifest["body"]
+      sha256(
+        "frontmatter" => normalize_value(frontmatter),
+        "runtype" => runtype_block.is_a?(Hash) ? normalize_value(runtype_block) : {},
+        "body" => body.is_a?(String) ? body : ""
+      )
+    end
+
+    # @param definition [Hash] `{ name:, description:, toolType:, parametersSchema:, config: }`.
+    # @return [String] SHA-256 hex; the name is identity, not content.
+    def tool(definition)
+      wire = stringify(definition)
+      normalized = {}
+      normalized["toolType"] = wire["toolType"] if wire.key?("toolType")
+      normalized["description"] = wire["description"] if truthy?(wire["description"])
+      normalized["parametersSchema"] = object_or_empty(wire["parametersSchema"])
+      normalized["config"] = object_or_empty(wire["config"])
+      sha256(normalized)
+    end
+
+    # @param definition [Hash] `{ name:, type:, behavior:?, inbound:?, outbound:?, status:? }`.
+    # @return [String] SHA-256 hex.
+    def surface(definition)
+      wire = stringify(definition)
+      type_entry = wire.key?("type") ? { "type" => wire["type"] } : {}
+      behavior = wire["behavior"]
+      normalized = type_entry.dup
+      normalized["behavior"] = behavior.is_a?(Hash) ? normalize_value(type_entry.merge(behavior)) : type_entry.dup
+      normalized["status"] = truthy?(wire["status"]) ? wire["status"] : "draft"
+      normalized["environment"] = "development"
+      sha256(normalized)
+    end
+
+    # @param definition [Hash] `{ name:, description:?, icon:?, spec:? }`.
+    # @return [String] SHA-256 hex; the name is identity, not content.
+    def product(definition)
+      wire = stringify(definition)
+      normalized = {}
+      normalized["description"] = wire["description"] if truthy?(wire["description"])
+      normalized["icon"] = wire["icon"] if truthy?(wire["icon"])
+      normalized["spec"] = object_or_empty(as_saved_stack(wire["spec"]))
+      sha256(normalized)
+    end
+
+    # @param fpo [Hash] a Full Product Object.
+    # @return [String] SHA-256 hex; `_meta` and `product.name` are excluded.
+    def fpo(fpo)
+      wire = stringify(fpo)
+      normalized = {}
+      normalized["version"] = normalize_value(wire["version"]) unless wire["version"].nil?
+      normalized["product"] = normalize_value(plain(wire["product"]).except("name"))
+      %w[capabilities tools surfaces].each { |section| normalized[section] = normalize_value(wire[section] || []) }
+      FPO_OPTIONAL_SECTIONS.each do |section|
+        normalized[section] = normalize_value(wire[section]) unless wire[section].nil?
+      end
+      sha256(normalized)
+    end
+
+    # @param definition [Hash] an eval suite `{ name:, target:, cases:, virtual:, ... }`.
+    # @return [String] SHA-256 hex; cases sort by name, grader order is kept.
+    def eval_suite(definition)
+      wire = stringify(definition)
+      mode = truthy?(wire["recordedToolMode"]) ? wire["recordedToolMode"] : "next_step"
+      policy = truthy?(wire["recordedToolUnmatchedPolicy"]) ? wire["recordedToolUnmatchedPolicy"] : "fail"
+      canonical = {}
+      canonical["target"] = sort_keeping_nil(wire["target"]) if wire.key?("target")
+      canonical["virtual"] = wire["virtual"] if wire.key?("virtual")
+      canonical["recordedToolMode"] = mode unless mode == "next_step"
+      canonical["recordedToolUnmatchedPolicy"] = policy unless policy == "fail"
+      cases = Array(wire["cases"]).map { |entry| plain(entry) }
+      canonical["cases"] = cases.each_with_index
+                                .sort_by { |entry, index| [utf16(entry["name"].to_s), index] }
+                                .map { |entry, _index| canonical_case(entry) }
+      sha256(canonical)
+    end
+
+    # Drops nil entries and orders object keys the way `JSON.stringify` emits
+    # sorted keys, recursively; arrays keep their order.
+    #
+    # @param value [Object]
+    # @return [Object]
+    def normalize_value(value)
+      case value
+      when Array then value.map { |entry| normalize_value(entry) }
+      when Hash
+        entries = stringify(value)
+        entries.keys.sort_by { |key| json_key_order(key) }.each_with_object({}) do |key, out|
+          out[key] = normalize_value(entries[key]) unless entries[key].nil?
+        end
+      else value
+      end
+    end
+
+    # @return [String]
+    def sha256(value)
+      Digest::SHA256.hexdigest(Runtype::CanonicalJSON.generate(value))
+    end
+
+    def canonical_case(entry)
+      canonical = {}
+      canonical["name"] = entry["name"] if entry.key?("name")
+      canonical["input"] = sort_keeping_nil(entry["input"]) if entry.key?("input")
+      canonical["expected"] = sort_keeping_nil(entry["expected"]) if entry.key?("expected")
+      canonical["expect"] = Array(entry["expect"]).map { |grader| sort_keeping_nil(grader) }
+      canonical
+    end
+
+    def normalize_flow_step(step)
+      normalized = {
+        "type" => step["type"].is_a?(String) ? step["type"] : "",
+        "name" => step["name"].is_a?(String) ? step["name"] : "",
+        "enabled" => step["enabled"] != false
+      }
+      normalized["when"] = step["when"] if step["when"].is_a?(String)
+      normalized["config"] = normalize_flow_config(step["config"])
+      normalized["order"] = step_order(step)
+      normalized
+    end
+
+    # Sorts keys and keeps nil; one level of array items is normalized, deeper
+    # arrays keep their insertion key order, exactly as the TypeScript SDK does.
+    def normalize_flow_config(config)
+      return {} unless config.is_a?(Hash)
+
+      entries = stringify(config)
+      entries.keys.sort_by { |key| json_key_order(key) }.each_with_object({}) do |key, out|
+        value = entries[key]
+        out[key] =
+          case value
+          when Hash then normalize_flow_config(value)
+          when Array then value.map { |item| item.is_a?(Hash) ? normalize_flow_config(item) : js_emission_order(item) }
+          else value
+          end
+      end
+    end
+
+    # The key order `JSON.stringify` gives an object nobody sorted: canonical
+    # array indexes first, then insertion order.
+    def js_emission_order(value)
+      case value
+      when Array then value.map { |entry| js_emission_order(entry) }
+      when Hash
+        entries = stringify(value)
+        indexes, others = entries.keys.partition { |key| json_key_order(key).first.zero? }
+        (indexes.sort_by { |key| json_key_order(key) } + others).to_h { |key| [key, js_emission_order(entries[key])] }
+      else value
+      end
+    end
+
+    def sort_keeping_nil(value)
+      case value
+      when Array then value.map { |entry| sort_keeping_nil(entry) }
+      when Hash
+        entries = stringify(value)
+        entries.keys.sort_by { |key| json_key_order(key) }.to_h { |key| [key, sort_keeping_nil(entries[key])] }
+      else value
+      end
+    end
+
+    # A legacy step missing `name`/`order` defaults to `Step N`/`N`, as flow pull emits.
+    def legacy_flow_step_identity(step, index)
+      step.merge(
+        "name" => step["name"].is_a?(String) ? step["name"] : "Step #{index + 1}",
+        "order" => step["order"].is_a?(Numeric) ? step["order"] : index + 1
+      )
+    end
+
+    def step_order(step)
+      order = step.is_a?(Hash) ? step["order"] : nil
+      order.is_a?(Numeric) ? order : 0
+    end
+
+    def json_key_order(key)
+      if key.match?(/\A(?:0|[1-9]\d*)\z/) && key.to_i <= MAX_ARRAY_INDEX
+        [0, key.to_i, []]
+      else
+        [1, 0, utf16(key)]
+      end
+    end
+
+    def utf16(value)
+      value.encode("UTF-16LE").unpack("v*")
+    end
+
+    def object_or_empty(value)
+      value.is_a?(Hash) ? normalize_value(value) : {}
+    end
+
+    # `spec` with its stack as a save stores it: server-set fields dropped, `hidden` deduplicated.
+    def as_saved_stack(spec)
+      return spec unless spec.is_a?(Hash)
+
+      wire = stringify(spec)
+      return wire unless wire["stack"].is_a?(Hash)
+
+      stack = stringify(wire["stack"]).except(*SERVER_SET_STACK_FIELDS)
+      stack["hidden"] = stack["hidden"].uniq if stack["hidden"].is_a?(Array)
+      wire.merge("stack" => stack)
+    end
+
+    def plain(value)
+      value.is_a?(Hash) ? stringify(value) : {}
+    end
+
+    def stringify(value)
+      value.is_a?(Hash) ? value.to_h { |key, entry| [key.to_s, entry] } : {}
+    end
+
+    # JavaScript truthiness for the values a definition can hold.
+    def truthy?(value)
+      !(value.nil? || value == false || value == "" || (value.is_a?(Numeric) && value.zero?))
+    end
+
+    private_class_method :canonical_case, :normalize_flow_step, :normalize_flow_config, :js_emission_order,
+                         :sort_keeping_nil, :step_order, :json_key_order, :utf16, :object_or_empty, :plain,
+                         :stringify, :truthy?
+  end
+end