feat(etl-uvicorn): own the /invoke transport and invocation-context model (0.1.0)

[CyMule]

Summary

This package now owns the transport for the reserved /invoke fields and the identity model they carry:
unstructured_platform_plugins.invocation_settings holds the ASGI middleware, the /metadata
capability route, the request-scoped binding, and http_status_for — the HTTP spelling of the
library's normative blame → status rule; unstructured_platform_plugins.invocation_context
holds the invocation_context contract (InvocationContext, extract_context, dimensions,
RESERVED_CONTEXT_KEY, DIMENSION_FIELDS, SUPPORTED_CONTEXT_VERSIONS,
UnsupportedContextVersionError).

It sits on utic-invocation-settings >=0.4.0
(Unstructured-IO/utic-public-libs#67), which owns the settings contract — which key carries
settings, how a sealed envelope is told from plaintext, and what an absent field is allowed to
mean. Nothing about the sealed-settings wire format is decided in this repository.

Why the split lands this way

• The absence rule (absent may fall back, anything that arrived must open or fail) is the
  tenant-confusion vector. It belongs beside the crypto and the threat model, not here.
• The invocation_context model is /invoke protocol identity — no crypto, no secrets — so it
  lives with the plugin protocol this package defines. Its errors subclass the shared
  InvocationSettingsError taxonomy, so hosts classify context failures with the same
  reason/blame machinery as settings failures. This module is the public home for the surface
  utic-invocation-settings 0.2.x carried and its 0.3.0 removed.
• Body buffering, 413 limits, replay, route registration, and the HTTP spelling of blame belong
  here, where a web framework is already a hard dependency and the middleware emits the responses.
• The library stays cryptography + pydantic with no framework test dependencies.

What the wrapper does

• wrap_in_fastapi / generate_fast_api install the middleware and register /metadata at
  construction. Repeated installation is safe: the middleware installs once, and the last
  /metadata registration wins regardless of route order.
• Opt-in invoke_with_sealed_dag_node_settings (and --sealed-dag-node-settings) advertises the
  capability. Opt-in because it asserts the wrapped function consumes
  current_invocation_settings(), not merely that the host can resolve it.
• invoke_func copies the current context into the executor thread. run_in_executor drops
  contextvars, so a sync plugin would otherwise see request-scoped bindings as absent and could
  take an unintended fallback path.
• SettingsScopedCache + settings_cache_key give per-invoke consumers one home for deriving
  state (clients, models, handlers) from the settings the middleware binds: memoized on a digest
  of the canonical settings JSON (secret-bearing payloads are never raw keys), bounded by both
  size and age so state built from since-rotated credentials cannot outlive them. Stdlib-only.

Two behaviours worth review

• Resolution runs off the event loop (asyncio.to_thread). A cold resolve is an RSA unwrap of
  ~2.2 ms and this middleware fronts every invoke on the pod.
• Failure responses declare whose fault it is, instead of encoding blame in status codes.
  The invoke envelope gains an optional blame, set to "user" only when the plugin raised the
  UserError family — a fault in something the customer owns (their file, their credentials,
  their provider). Absent means not-the-customer's: an orchestrator must never infer customer
  fault from the status class, which also carries transport semantics. Middleware error bodies
  carry the invocation-settings taxonomy reason code alongside detail for the same purpose —
  a platform-composed payload failure is recognizable whatever status answered the hop. Both
  fields are inert until an orchestrator consumes them (Unstructured-IO/platform-plugins#1925).
• Failures map through the shared blame taxonomy via http_status_for, not a flat 500. Only
  a caller-fixable fault answers 422; sealing drift, an envelope for another recipient and a broken
  local mount are all 5xx, which keeps the controller's blame classification off the customer.
  Responses carry the error's class name and never its message, which can embed request-controlled
  values.

Impact

• requires utic-invocation-settings >=0.4.0,<1.0.0
• Python 3.10 users remain on the 0.0.x release line

Validation

• 145 passed: 84 pre-existing tests unchanged (installation is inert for existing plugins) + 25 transport tests (sealed/composite/plaintext/absent resolution, blame-mapped statuses, the 413 cap, disconnect replay, /metadata last-call-wins, sync-executor context propagation, secrets never in logs or response text) + 12 settings-scoped cache tests (key hygiene, TTL and LRU bounds) + 4 blame/reason declaration tests + 20 invocation-context and status-mapping tests (extraction fail-closed rules, version gate, dimension policy, http_status_for)
• Ruff clean on all changed files

Draft follow-ups

• regenerate uv.lock once utic-invocation-settings 0.4.0 is published
• update CI, release, and dependency-compilation configuration to use Python 3.11 as the minimum