coolhand 0.7.0 → 0.9.0

data/docs/openai.md

@@ -14,7 +14,7 @@ Requires Rails — `Coolhand::WebhookInterceptor` and `Coolhand::OpenAi::BatchRe
 - Ensure you skip CSRF for the webhook endpoint: `skip_before_action :verify_authenticity_token`
 - Override the `webhook_secret` method to return your OpenAI webhook secret
 
-`intercept_batch_request` already validates the webhook and, for `batch.completed`/`batch.failed`/`batch.expired`/`batch.cancelled` events, calls `Coolhand::OpenAi::BatchResultProcessor` **synchronously**, inline in the `before_action` — that part requires no code in your controller action. It downloads two JSONL files from OpenAI and sends one request log per batch item, so a large batch can take long enough to trip your webhook endpoint's timeout (and OpenAI's retry behavior); consider that when sizing batches. The example below shows a controller action doing additional, app-specific work on top of that (e.g. updating your own `BatchApiRequest` record and enqueuing your own background job), which is optional.
+`intercept_batch_request` already validates the webhook and, for `batch.completed`/`batch.failed`/`batch.expired`/`batch.cancelled` events, calls `Coolhand::OpenAi::BatchResultProcessor` — that part requires no code in your controller action. The batch's status is checked inline in the `before_action`, but for a completed batch the two JSONL file downloads and the one-request-log-per-item sends run on Coolhand's [background log thread](configuration.md#asynchronous-logging), so a large batch doesn't hold up your webhook response. (With `config.async_logging = false` this all runs inline, and a large batch can trip your webhook endpoint's timeout and OpenAI's retry behavior.) The example below shows a controller action doing additional, app-specific work on top of that (e.g. updating your own `BatchApiRequest` record and enqueuing your own background job), which is optional.
 
 ## Minimal example
 
@@ -59,6 +59,10 @@ end
 # ...existing code...
 ```
 
+## Signature header and secret rotation
+
+The `webhook-signature` header may carry several space-separated signatures (`v1,sigA v1,sigB`), as senders produce while a webhook secret is being rotated. `Coolhand::OpenAi::WebhookValidator` accepts the request if any `v1,` entry matches your secret, comparing each in constant time and ignoring entries with any other version prefix. The timestamp and replay checks below still run, and only after a signature matches.
+
 ## Replay protection
 
 `Coolhand::OpenAi::WebhookValidator` rejects requests whose `webhook-timestamp` is more than **300 seconds** away from the current time, and rejects a `webhook-id` it has already seen within that window — this prevents a captured request (from a log aggregator, APM trace, or proxy log) from being replayed to re-trigger `Coolhand::OpenAi::BatchResultProcessor`.

data/docs/template-search.md

@@ -41,7 +41,7 @@ This is **not** a port of the `search_templates` MCP tool, and the two do not ag
 Template *creation, update and deprecation* stay on the MCP surface. This REST surface is
 read-only, and there is no version-history sub-resource.
 
-## `search_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil, include_system: nil, page: nil, per: nil)`
+## `search_templates(search: nil, workload_id: nil, status: nil, include_deprecated: nil, include_system: nil, include_metrics: nil, days_back: nil, since: nil, until: nil, page: nil, per: nil)`
 
 Search is a *parameter* on the list endpoint rather than a route of its own, so this is one method
 rather than a list/search pair.
@@ -56,6 +56,10 @@ and this API's already agree, so there is no second spelling to translate throug
 | `status` | String | `"draft"`, `"published"` or `"failure"`. Any other non-empty value is a `422` from the server; empty is treated as no filter. |
 | `include_deprecated` | Boolean | Include templates with a non-null `deprecated_at`. Defaults to `false` server-side. |
 | `include_system` | Boolean | Include the `Unmatched` / `Ignored API Calls` buckets. Defaults to `false` server-side. |
+| `include_metrics` | Boolean | Adds a `:metrics` Hash to every row. See [Metrics](#metrics). |
+| `days_back` | Integer | Rolling metrics window in days (server default 28, max 365). Ignored unless metrics are requested, and when `since` is given. |
+| `since` | Time, DateTime, Date or String | Metrics window start, inclusive. Overrides `days_back`. |
+| `until` | Time, DateTime, Date or String | Metrics window end, exclusive. Defaults to now. |
 | `page` | Integer | 1-based. |
 | `per` | Integer | Default 25, max 100, both enforced server-side. |
 
@@ -138,11 +142,14 @@ unmatched = Coolhand.template_service
 puts unmatched[:log_count]
 ```
 
-## `get_template(id)`
+## `get_template(id, include_metrics: nil, days_back: nil, since: nil, until: nil)`
 
 `id` is the template hashid — the `:id` field from `search_templates`.
 
-Returns a Hash with every list field above, **plus** the full untruncated regexes the list omits:
+Returns a Hash with every list field above, **plus** the full untruncated regexes the list omits, and
+a `:metrics` Hash. Unlike the list, metrics are **on by default** here: pass `include_metrics: false` to
+omit them, which also skips the window validation. `days_back`, `since` and `until` set the window
+exactly as they do on the list, and an invalid one is a `422` unless metrics are off.
 
 | field | type |
 |---|---|
@@ -153,6 +160,41 @@ Unlike the list, this filters on nothing but client ownership: a deprecated or s
 reachable by id with **no opt-in flag**, because inspecting one of those is the usual reason to
 fetch a template directly.
 
+## Metrics
+
+With `include_metrics: true` every row (and by default the `get_template` result) carries `:metrics`,
+computed by the same SQL as the dashboard, so tiered pricing, cached-token discounts and reasoning tokens
+are applied. `Coolhand.workload_service` returns the same object per workload, rolled up across its
+templates ([Reading Workloads](workload-search.md)).
+
+Averages and counters cover non-failed, directly-collected client logs inside the window. Keys are the
+wire names, as Symbols.
+
+| field | type | notes |
+|---|---|---|
+| `:days_back` | Integer or nil | `nil` when `since` defined the window. |
+| `:since`, `:until` | String | The resolved window, ISO-8601 UTC. |
+| `:request_count` | Integer | |
+| `:failure_count` | Integer | Failed logs. |
+| `:error_rate` | Float or nil | `nil` when `failure_count` is 0. |
+| `:error_rate_change` | Float or nil | Against the window of the same length immediately before. |
+| `:avg_cost_per_request` | Float or nil | `nil` when no log in the window could be priced. |
+| `:total_cost` | Float or nil | |
+| `:priced_request_count` | Integer | The logs `total_cost` covers: non-failed, with tokens, model has pricing. |
+| `:long_context_request_count` | Integer | Priced logs that crossed their model's input-token pricing tier. |
+| `:total_input_tokens`, `:total_output_tokens` | Integer | Raw token columns summed over non-failed logs, not cache-adjusted. |
+| `:avg_input_tokens`, `:avg_output_tokens` | Integer or nil | |
+| `:avg_latency_ms` | Float or nil | |
+| `:correctness_score`, `:sentiment_score`, `:revision_score` | Float or nil | `sentiment_score` and `revision_score` are all-time, not windowed. |
+| `:first_request_at`, `:last_request_at` | String or nil | Lifetime, not windowed. |
+
+Summing the per-log `cost` from [Reading Logs](log-search.md) can exceed `total_cost`, because the log
+`cost` is also computed for failed logs and logs with a zero token count.
+
+Windows follow the rules in [Reading Workloads](workload-search.md#windows-since-and-until). A window
+error is a `422` on the `since` or `until` key. Metrics add aggregate statements, so expect a slower
+response, and a `504` on a large page.
+
 ## Errors
 
 The write methods in this gem (`create_feedback`, `create_log`, `send_llm_request_log`) log a
@@ -186,7 +228,7 @@ end
 |---|---|
 | `401` | Missing, invalid, or public API key. |
 | `404` | `get_template` only. Unknown id, **or** one belonging to another client — existence is not disclosed, so this is never a `403`. |
-| `422` | Unrecognised `status`, or a `workload_id` that does not decode or belongs to another client. |
+| `422` | Unrecognised `status`, a `workload_id` that does not decode or belongs to another client, or a bad `days_back`, `since` or `until` when metrics are requested. |
 | `504` | See below. |
 
 ### `504` is expected, and retryable

data/docs/vertex.md

@@ -15,6 +15,7 @@ require "coolhand/vertex/batch_result_processor"
 ```
 
 - Call the `Coolhand::Vertex::BatchResultProcessor` service with `batch_info` and the downloaded batch results.
+- For a succeeded job, the per-item request logs are sent from Coolhand's [background log thread](configuration.md#asynchronous-logging) as a single job, so `call` returns without waiting on the Coolhand API (set `config.async_logging = false` to send inline).
 - Optionally pass `model:` to populate the logged `model` field. It falls back to a `"model"` key in `batch_info` if present, and is omitted from the payload entirely when neither is available. If the value (from either source) looks like a Vertex model resource path (`publishers/<publisher>/models/<id>` or `projects/<project>/locations/<location>/models/<id>`), it's normalized down to just the trailing id/version before being logged; any other string is sent as-is.
 - `batch_info["name"]` must be the exact Vertex job resource name (`projects/<project>/locations/<location>/batchPredictionJobs/<job-id>`), and `batch_info["startTime"]`/`["endTime"]` must be valid ISO 8601 timestamps — a batch with a missing or malformed resource name or timestamps is skipped entirely (logged as an error) rather than sent with a broken URL.
 - If `endTime` precedes `startTime` (e.g. clock skew), the batch is still logged — `duration_ms` is clamped to `0` and a warning is logged — rather than dropping the results.

data/docs/workload-search.md

@@ -0,0 +1,116 @@
+# Reading Workloads (Search)
+
+`Coolhand::WorkloadService#search_workloads` lists your workloads, the groups of prompt templates that
+make up one task or agent, optionally with a cost and performance `metrics` rollup per workload. It
+wraps `GET /api/v2/workloads`. It is read-only, and there is no per-workload endpoint.
+
+**Auth:** requires your **private** API key. The public key is write-only on this API and is rejected
+exactly like an invalid key.
+
+**IDs:** a workload's `:id` is its **hashid**, a String. It is what the `workload_id` filter on
+`search_templates` and `search_logs` expects.
+
+**Scoping:** the client is always derived from your API key. There is deliberately no `client_id`
+keyword, so passing one raises `ArgumentError`.
+
+## `search_workloads`
+
+```ruby
+require "coolhand"
+
+Coolhand.configure do |config|
+  config.api_key = ENV.fetch("COOLHAND_PRIVATE_API_KEY")
+end
+
+result = Coolhand.workload_service.search_workloads(
+  include_metrics: true,
+  since: Time.utc(2026, 9, 1),
+  until: Time.utc(2026, 10, 1),
+  per: 50
+)
+
+result.workloads.each do |workload|
+  puts "#{workload[:name]}: $#{workload[:metrics][:total_cost]}"
+end
+```
+
+### Keywords
+
+All optional, and named exactly like the wire parameters.
+
+| keyword | type | notes |
+|---|---|---|
+| `search` | String | Case-insensitive substring match on the workload name. |
+| `include_archived` | Boolean | Defaults to `false` server-side. |
+| `include_system` | Boolean | `Unmatched`, `Embedding Requests` and the like. Defaults to `false` server-side. |
+| `include_templates` | Boolean | Adds each workload's active templates and their routing patterns as `:templates`. |
+| `include_metrics` | Boolean | Adds a `:metrics` rollup across all of the workload's templates. |
+| `days_back` | Integer | Rolling metrics window ending now (server default 28, max 365). Ignored when `since` is given. |
+| `since` | Time, DateTime, Date or String | Metrics window start, inclusive. Overrides `days_back`. |
+| `until` | Time, DateTime, Date or String | Metrics window end, exclusive. Defaults to now. |
+| `page` | Integer | 1-based. |
+| `per` | Integer | Default 25, max 100, both enforced server-side. This gem only sends `per`, never its `per_page` alias. |
+
+`false` and `0` are sent as given; only an unset (`nil`) keyword is left off the request.
+
+### Windows: `since` and `until`
+
+`Time`, `DateTime` and `Date` values are serialised as UTC ISO8601 (a `Date` as a date alone, which the
+server reads as midnight UTC). A String is passed through untouched, so the server stays the one
+validator. Anything else raises `ArgumentError` before a request is made.
+
+```ruby
+search_workloads(include_metrics: true, since: "2026-09-01")                 # date alone: midnight UTC
+search_workloads(include_metrics: true, since: "2026-09-01T12:00:00+02:00")  # the + is encoded as %2B for you
+```
+
+Server-side rules, which only apply when `include_metrics` is set:
+
+- A missing offset means UTC. `since` is inclusive and `until` is exclusive.
+- With `since`, `days_back` is ignored and `metrics[:days_back]` is `nil`. With only `until`, the window
+  is `days_back` long ending there.
+- The prior window behind `error_rate_change` is the same length, immediately before the window.
+- A malformed value, a `since` not before `until`, or a window over 365 days is a `422` with the error on
+  the `since` or `until` key.
+
+### Return value
+
+A `Coolhand::WorkloadSearchResult`, a `Struct` with `#workloads` and `#pagination`. Rows are plain
+Hashes with Symbol keys, handed back as the API rendered them so a field the server adds later reaches
+you.
+
+| field | type | notes |
+|---|---|---|
+| `:id` | String | Hashid. |
+| `:name` | String | |
+| `:description` | String or nil | |
+| `:archived`, `:system`, `:merged` | Boolean | |
+| `:template_count` | Integer | Active templates. |
+| `:draft_template_count` | Integer | |
+| `:log_count` | Integer | Every log on any of its templates, all generators, so it can exceed the sum of the templates' own `log_count`. |
+| `:last_activity` | String or nil | ISO-8601 UTC. |
+| `:templates` | Array | Only with `include_templates`. Each has `:id`, `:name`, `:status`, `:user_prompt_pattern`, `:system_prompt_pattern`. |
+| `:metrics` | Hash | Only with `include_metrics`. See below. |
+
+Rows are ordered by name. `pagination` is a `Coolhand::Pagination` built from the `X-Page`,
+`X-Per-Page`, `X-Total-Count` and `X-Total-Pages` response headers, which this endpoint always sends,
+never from the length of the array.
+
+### `metrics`
+
+The same object `search_templates` returns per template, computed by the same SQL as the dashboard, so
+tiered pricing, cached-token discounts and reasoning tokens are applied. See
+[Metrics](template-search.md#metrics) for every field.
+
+## Errors
+
+The read methods raise where the write methods log and return `nil`. `Coolhand::HttpError` carries
+`#status` and `#body` (`{"errors": {"<field>": ["msg"]}}` on a `422`).
+
+| status | when |
+|---|---|
+| `401` | No API key, an invalid key, or the public key. |
+| `422` | A bad `days_back`, `since` or `until`. Only checked when `include_metrics` is set. |
+| `504` | An aggregate exceeded the server's statement timeout. Retryable: narrow with `search` or a smaller `per`. |
+
+`Coolhand::Error` covers no API key configured, a transport failure, and a body that is not a JSON array.

data/lib/coolhand/api_service.rb

@@ -6,12 +6,14 @@ require "json"
 require_relative "collector"
 require_relative "errors"
 require_relative "read_requests"
+require_relative "response_warnings"
 
 module Coolhand
   class ApiService
     # The GET half of this class. See Coolhand::ReadRequests for why reads raise where writes
     # log and return nil.
     include ReadRequests
+    include ResponseWarnings
 
     # Caps how much of a failed response body is interpolated into a log line or an exception
     # message. Without it an oversized body from a proxy or gateway becomes the message.
@@ -36,7 +38,9 @@ module Coolhand
         log JSON.pretty_generate(sanitize_payload_for_json(payload))
         nil
       else
-        send_request(payload, "✅ Successfully sent request metadata")
+        result = send_request(payload, "✅ Successfully sent request metadata")
+        log_response_warnings(result)
+        result
       end
     end
 
@@ -80,9 +84,10 @@ module Coolhand
       uri = URI.parse(@api_endpoint)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl = (uri.scheme == "https")
-      # Bound worst-case latency: this call happens inline in the intercepted
-      # request's path, so a slow/unreachable Coolhand backend must not hang
-      # the host app's real LLM call for Ruby's ~60s Net::HTTP defaults.
+      # Bound worst-case latency: with async_logging off this call happens inline in
+      # the intercepted request's path (otherwise it ties up the background log
+      # worker), so a slow/unreachable Coolhand backend must not hang for Ruby's
+      # ~60s Net::HTTP defaults.
       http.open_timeout = 5
       http.read_timeout = 5
 

data/lib/coolhand/base_interceptor.rb

@@ -149,7 +149,8 @@ module Coolhand
     end
 
     def send_complete_request_log(request_id:, method:, url:, request_headers:, request_body:, response_headers:,
-      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil)
+      response_body:, status_code:, start_time:, end_time:, duration_ms:, is_streaming:, source_api: nil, model: nil,
+      declared: nil)
       raw_request = {
         id: request_id,
         timestamp: start_time.iso8601,
@@ -168,11 +169,12 @@ module Coolhand
       raw_request[:model] = model if Coolhand.required_field?(model)
 
       request_data = { raw_request: raw_request }
+      request_data[:declared] = declared if declared && !declared.empty?
 
-      api_service = Coolhand::ApiService.new
-      api_service.send_llm_request_log(request_data)
-
-      Coolhand.log "📤 Sent complete request/response log for #{request_id} (duration: #{duration_ms}ms)"
+      LogQueue.submit do
+        Coolhand::ApiService.new.send_llm_request_log(request_data)
+        Coolhand.log "📤 Sent complete request/response log for #{request_id} (duration: #{duration_ms}ms)"
+      end
     rescue StandardError => e
       Coolhand.log "❌ Error sending complete request log: #{e.message}"
     end

data/lib/coolhand/configuration.rb

@@ -29,8 +29,8 @@ module Coolhand
     DEFAULT_MAX_CAPTURED_BODY_BYTES = 1_000_000
 
     attr_accessor :api_key, :environment, :silent, :debug_mode, :capture, :exclude_api_patterns, :enabled,
-      :max_captured_body_bytes, :webhook_replay_tolerance_seconds, :webhook_id_store
-    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url
+      :max_captured_body_bytes, :webhook_replay_tolerance_seconds, :webhook_id_store, :async_logging
+    attr_reader :intercept_addresses, :intercept_path_patterns, :base_url, :auto_declare
 
     def initialize
       # Set defaults
@@ -44,6 +44,8 @@ module Coolhand
       @capture = true
       @exclude_api_patterns = DEFAULT_EXCLUDE_API_PATTERNS.dup
       @enabled = true
+      @async_logging = true
+      @auto_declare = []
       @max_captured_body_bytes = DEFAULT_MAX_CAPTURED_BODY_BYTES
       @webhook_replay_tolerance_seconds = 300
       @webhook_id_store = Coolhand::OpenAi::WebhookIdStore.new
@@ -73,6 +75,18 @@ module Coolhand
       @intercept_path_patterns = value.is_a?(Array) ? value : [value]
     end
 
+    # Rails entry points to declare a workload/template for automatically: any of
+    # RailsAutoDeclare::TARGETS (:active_job, :controller). Off by default. See docs/declared_workloads.md.
+    def auto_declare=(value)
+      targets = Array(value).map { |target| target.to_s.to_sym }
+      unknown = targets - RailsAutoDeclare::TARGETS
+      unless unknown.empty?
+        raise Error, "auto_declare supports #{RailsAutoDeclare::TARGETS.inspect}, got #{unknown.inspect}"
+      end
+
+      @auto_declare = targets.uniq
+    end
+
     def base_url=(value)
       stripped = value&.sub(%r{/+\z}, "")
       raise Error, BASE_URL_ERROR_MSG unless stripped.nil? || valid_base_url?(stripped)

data/lib/coolhand/declarable.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Declares the workload/template of the LLM calls a class makes, once, on the class, so passive
+  # capture picks them up without a `Coolhand.with_context` block at every call site. Wrapped methods
+  # run inside `with_context`, so nesting and precedence are exactly those documented in
+  # docs/declared_workloads.md. Settings are inherited by subclasses.
+  #
+  #   class ApplicationService
+  #     include Coolhand::Declarable
+  #     coolhand_workload reporter: "my-app"
+  #     coolhand_declare_all
+  #   end
+  #
+  #   class Parser < ApplicationService
+  #     def call = client.chat(...) # workload "Parser#call", template "Parser#call"
+  #   end
+  module Declarable
+    def self.included(base)
+      raise ArgumentError, "Coolhand::Declarable can only be included in a class" unless base.is_a?(Class)
+
+      base.extend(ClassMethods)
+    end
+
+    # Never an LLM call site, and wrapping them would tax every call or declare a junk workload.
+    SKIPPED_METHODS = %i[method_missing respond_to? respond_to_missing? == === eql? equal? hash to_s inspect
+                         to_str to_ary to_proc coerce <=>].freeze
+    ATTRIBUTE_MACROS = %w[attr attr_reader attr_writer attr_accessor].freeze
+    private_constant :SKIPPED_METHODS, :ATTRIBUTE_MACROS
+
+    module ClassMethods
+      # Class-level defaults, inherited field by field (the nearest class that sets a field wins). With
+      # no `key`, each wrapped method declares its own workload, "ClassName#method"; a `key` makes every
+      # method share one workload. The class name is the runtime class, so an inherited method declares
+      # under the subclass.
+      def coolhand_workload(key: nil, name: nil, description: nil, reporter: nil)
+        workload = DeclaredContext.normalize_part(:workload, { key: key, name: name, description: description }.compact,
+          DeclaredContext::WORKLOAD_FIELDS)
+        @coolhand_settings = { workload: workload, reporter: DeclaredContext.normalize_reporter(reporter) }.compact
+      end
+
+      # Wraps the named instance methods (now, or when they are defined later). `template:` is a key or a
+      # `{ key:, name: }` Hash; by default the template key is "ClassName#method".
+      def coolhand_declare(*names, template: nil)
+        # Checked here, at class definition, so a bad value never surfaces inside the host's method.
+        template = DeclaredContext.normalize_part(:template, template.is_a?(String) ? { key: template } : template,
+          DeclaredContext::TEMPLATE_FIELDS)
+        names.flatten.each do |name|
+          name = name.to_sym
+          (@coolhand_declared ||= {})[name] = { template: template }
+          coolhand_wrap(name) if method_defined?(name) || private_method_defined?(name)
+        end
+      end
+
+      # Wraps every public instance method defined in this class and its subclasses after this call, so
+      # put it at the top of the class body. Private and protected methods, attribute readers/writers
+      # and object-protocol methods (see SKIPPED_METHODS) are left alone; `coolhand_declare` wraps one of
+      # those if you name it.
+      def coolhand_declare_all
+        @coolhand_declare_all = true
+      end
+
+      # @api private
+      def coolhand_identity(method_name)
+        key = "#{name}##{method_name}"
+        template = coolhand_template_for(method_name)
+        {
+          reporter: coolhand_setting(:reporter),
+          workload: { key: key }.merge(coolhand_setting(:workload) || {}),
+          template: template || { key: key }
+        }
+      end
+
+      # @api private
+      def coolhand_declare_call?(method_name)
+        return false if name.nil? || !Coolhand.configuration.enabled
+        return false unless DeclaredContext.valid_key?("#{name}##{method_name}")
+
+        public_method_defined?(method_name) || !coolhand_declaration(method_name).nil?
+      end
+
+      # @api private
+      def coolhand_own_state
+        [@coolhand_settings, @coolhand_declared, @coolhand_declare_all]
+      end
+
+      private
+
+      def method_added(method_name)
+        super
+        coolhand_wrap(method_name) if !@coolhand_wrapping && coolhand_wrap?(method_name)
+      end
+
+      def coolhand_wrap?(method_name)
+        return true if coolhand_declaration(method_name)
+
+        public_method_defined?(method_name) && !SKIPPED_METHODS.include?(method_name) &&
+          coolhand_declare_all? && !attribute_definition?
+      end
+
+      # True while `attr_reader`/`attr_writer`/`attr_accessor` is what is defining the method. Read from
+      # the stack rather than by overriding those macros, which would lose the class body's
+      # `private`/`protected` default visibility. A window of frames, not one fixed depth, so a
+      # `method_added` override that calls `super` does not hide the macro.
+      def attribute_definition?
+        caller_locations(1, 8)&.any? { |frame| ATTRIBUTE_MACROS.include?(frame.base_label) } || false
+      end
+
+      def coolhand_declare_all?
+        coolhand_each_class { |klass| return true if klass.coolhand_own_state[2] }
+        false
+      end
+
+      # Redefines the method in the same class, rather than prepending a wrapper, so a later
+      # `private :name` (or `private def name`) applies to the wrapper like it would to the original.
+      def coolhand_wrap(method_name)
+        original = instance_method(method_name)
+        wrappers = (@coolhand_wrappers ||= {})
+        return if wrappers[method_name] == original
+
+        visibility = coolhand_visibility(method_name)
+        @coolhand_wrapping = true
+        define_method(method_name) do |*args, **kwargs, &block|
+          klass = self.class
+          next original.bind_call(self, *args, **kwargs, &block) unless klass.coolhand_declare_call?(method_name)
+
+          Coolhand.with_context(**klass.coolhand_identity(method_name)) do
+            original.bind_call(self, *args, **kwargs, &block)
+          end
+        end
+        send(visibility, method_name)
+        wrappers[method_name] = instance_method(method_name)
+      ensure
+        @coolhand_wrapping = false
+      end
+
+      # Includes inherited methods: wrapping one a parent made private must not make it public here.
+      def coolhand_visibility(method_name)
+        return :private if private_method_defined?(method_name)
+        return :protected if protected_method_defined?(method_name)
+
+        :public
+      end
+
+      # Yields this class and its superclasses that include Declarable, nearest first. A loop rather
+      # than a collected Array, since the lookups below run on every wrapped call.
+      def coolhand_each_class
+        klass = self
+        while klass.respond_to?(:coolhand_own_state)
+          yield klass
+          klass = klass.superclass
+        end
+      end
+
+      def coolhand_declaration(method_name)
+        coolhand_nearest(1, method_name)
+      end
+
+      def coolhand_template_for(method_name)
+        coolhand_declaration(method_name)&.fetch(:template)
+      end
+
+      def coolhand_setting(field)
+        coolhand_nearest(0, field)
+      end
+
+      # The value for `key` in the nearest class whose own state (slot `slot` of `coolhand_own_state`)
+      # sets it, or nil.
+      def coolhand_nearest(slot, key)
+        coolhand_each_class do |klass|
+          state = klass.coolhand_own_state[slot]
+          return state[key] if state&.key?(key)
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/coolhand/declared_context.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Coolhand
+  # Ambient workload/template identity for captured calls, set with {Coolhand.with_context}. The
+  # interceptor snapshots {current} on the calling thread before a log is queued, because the
+  # background log worker does not inherit thread-locals. See docs/declared_workloads.md.
+  module DeclaredContext
+    THREAD_KEY = :coolhand_declared_context
+
+    # The fields the server accepts under `declared.workload` / `declared.template`; anything else
+    # is dropped here rather than sent.
+    WORKLOAD_FIELDS = %i[id key name description].freeze
+    TEMPLATE_FIELDS = %i[id key name].freeze
+
+    module_function
+
+    # A frozen Hash, or nil when no context is active.
+    def current
+      Thread.current[THREAD_KEY]
+    end
+
+    def clear!
+      Thread.current[THREAD_KEY] = nil
+    end
+
+    # Each field is replaced wholesale by the innermost block that sets it. Hashes are not merged
+    # key by key: `{ id: x }` merged with `{ key: y }` would declare both, and the server prefers `id`.
+    # A template belongs to a workload, so a block that declares a workload without a template does
+    # not inherit the outer one; it would pair the new workload with a template from another.
+    def with(reporter: nil, workload: nil, template: nil)
+      previous = current
+      declared = {
+        reporter: normalize_reporter(reporter),
+        workload: normalize_part(:workload, workload, WORKLOAD_FIELDS),
+        template: normalize_part(:template, template, TEMPLATE_FIELDS)
+      }.compact
+      inherited = previous || {}
+      inherited = inherited.except(:template) if declared.key?(:workload) && !declared.key?(:template)
+      merged = inherited.merge(declared)
+      ensure_template_has_workload!(merged)
+      Thread.current[THREAD_KEY] = merged.empty? ? nil : merged.freeze
+      yield
+    ensure
+      Thread.current[THREAD_KEY] = previous
+    end
+
+    def normalize_reporter(reporter)
+      return nil if reporter.nil?
+
+      reporter.to_s
+    end
+
+    # Mirrors the server's key rules: at most 255 characters, no control or invisible characters, no
+    # leading or trailing whitespace, and no leading, trailing or doubled "/". The server answers a
+    # bad key with a 422 that rejects the whole log, so it is checked here, before the call is made.
+    MAX_KEY_LENGTH = 255
+    KEY_FORMAT = %r{
+      \A(?!/)(?!.*//)
+      [^\p{Cntrl}\p{Cf}[:space:]]
+      (?:[^\p{Cntrl}\p{Cf}]*[^\p{Cntrl}\p{Cf}[:space:]])?
+      (?<!/)\z
+    }x
+
+    def valid_key?(key)
+      key.is_a?(String) && key.length <= MAX_KEY_LENGTH && KEY_FORMAT.match?(key)
+    rescue ArgumentError, EncodingError
+      false # a string with a broken or incompatible encoding is not a valid key
+    end
+
+    # A template given by key, with no workload to create it in, is a 422 that drops the log. A
+    # template `id` refers to an existing record and needs no workload.
+    def ensure_template_has_workload!(declared)
+      template = declared[:template]
+      return if template.nil? || template.key?(:id) || declared.key?(:workload)
+
+      raise ArgumentError, "template with a :key needs a workload; declare one in this or an enclosing block"
+    end
+
+    # Validated up front: the server answers a non-object `workload`/`template` with a 422 for the
+    # whole log, which would drop the call from Coolhand rather than just its identity.
+    def normalize_part(name, value, fields)
+      return nil if value.nil?
+      raise ArgumentError, "#{name} must be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+      part = value.each_with_object({}) do |(k, v), acc|
+        field = k.respond_to?(:to_sym) ? k.to_sym : nil
+        next unless fields.include?(field) && !v.nil?
+        # A blank id refers to nothing and would 422 the log, so it counts as not given.
+        next if field == :id && v.to_s.strip.empty?
+
+        acc[field] = v.to_s.dup.freeze
+      end
+      return nil if part.empty?
+
+      if part.key?(:key) && !valid_key?(part[:key])
+        raise ArgumentError, "#{name} key must be at most #{MAX_KEY_LENGTH} printable characters with no " \
+                             "surrounding whitespace and no leading, trailing or doubled \"/\""
+      end
+      unless part.key?(:id) || part.key?(:key)
+        raise ArgumentError, "#{name} needs an :id or a :key, got #{value.keys.inspect}"
+      end
+
+      part.freeze
+    end
+  end
+end

data/lib/coolhand/errors.rb

@@ -3,7 +3,8 @@
 module Coolhand
   class Error < StandardError; end
 
-  # Raised by the gem's read methods when the Coolhand API answers with a non-2xx status.
+  # Raised by the gem's raising API methods (template reads, feedback links) when the Coolhand API
+  # answers with a non-2xx status.
   #
   # `status` is carried so callers can branch on it (404 vs retryable 504) without matching the
   # message text.