Declarative per-request steering gates (when × scope × apply)

[RhizoNymph]

Lets a client attach its own conditional steering to a request — a nested list of when × scope × apply gates in the request payload — with no server-registered consumer. Bridges the static-easy / dynamic-hard cliff. Builds on the per-row monitor (#217).

Gate model

• when: always | probe (sigmoid(sharpness·(residual@probe − threshold)))
• scope: this_token | next_step | rest_of_request | rest_of_conversation
• apply: add (vector × strength, composed on top of the request's static decode steering) | attenuate (damp existing steering)

How it works

• Schema (vllm/v1/steering_schema.py): msgspec tagged unions carried on RequestMetadata.steering (like conversation_id). Vector source = {name} (server registry) or inline {packed} base64 escape hatch. Names resolve to packed at the frontend, so the worker only ever sees packed bytes — no worker-side registry. Unpacked to numpy once at admission and surfaced on StepRequestView.steering (v1 + v2).
• Built-in consumer (vllm/v1/capture/declarative.py): auto-registered (reserved name _declarative_steering) when steering is on, enable_declarative_gates is set (default), and pp==1; enabling it turns on enable_row_monitor. Subclasses SteeringController to reuse the conversation latch/bridge + _armed lifecycle, overrides on_step for multi-gate/multi-scope dispatch. probe × this_token runs in-graph every decode token via a per-request SteeringMonitorUpdate(req_id=) (free, cudagraph-safe); host-evaluated scopes read the captured residual on the CPU; rest_of_conversation latches + bridges turns.
• Substrate (steering_action_queue.py, steering_model_runner_mixin.py, steering_manager.py): RequestSteeringOverride.compose_admitted folds the request's admitted decode delta (add-on-top); _req_override_source enforces precedence (operator consumer wins over a client gate); release_dynamic_config purges the row's per-row monitor + scale so per-request gates leave no residue.
• Named vector registry (vllm/entrypoints/openai/steering/vector_registry.py + vllm/entrypoints/serve/steering/vectors_router.py): frontend-only probe/steer namespaces; POST /v1/steering/vectors/register|unregister, GET /v1/steering/vectors, gated by the steering API key + dev mode. Distinct from the module registry.

Locked design decisions

Nested-list schema; add composes on top; vector source name-first + inline packed; operator precedence wins. (See design doc §8.2.)

Config

--enable-declarative-gates (default on with steering), --declarative-probe-sites (host-probe capture allow-list). Off ⇒ zero behavior change.

Tests

CPU unit tests: schema build/resolve/roundtrip/validation (tests/v1/test_steering_schema.py), consumer on_step dispatch for all scope×apply combos + latch/bridge/pulse lifecycle (tests/v1/capture/test_declarative_consumer.py), the frontend registry (tests/entrypoints/openai/test_steering_vector_registry.py), and release_dynamic_config monitor/scale purge (tests/v1/worker/test_steering_declarative_cleanup.py). Existing steering suites remain green.

Remaining: GPU e2e (this_token+probe in-graph, rest_of_conversation latch, named-vector parity) — builds entirely on already-GPU-validated substrate (#217 row monitor, override pool).

Notes for sibling branches

Extends RequestMetadata (new steering field) and StepRequestView (new steering field) — expect trivial conflicts with any branch also touching those.