Omit unset optional request parameters

docs/roadmap/optional-request-parameters.md

@@ -0,0 +1,83 @@
+# Omit Unset Optional Request Parameters
+
+Status: Selected for implementation.
+
+## Purpose
+
+Promptkit will stop turning an unset optional provider control into an explicit
+outbound value. Required protocol fields and settings needed to enforce
+Promptkit's own contracts will retain defined behavior, while provider tuning
+choices will be sent only when a supported configuration layer selects them.
+
+This keeps profiles intentional, avoids overriding model- or backend-specific
+defaults, and improves compatibility across OpenAI-compatible endpoints with
+different supported parameter sets.
+
+## Scope
+
+The framework-level `top_p` default of `1` will become unspecified. When no
+profile or runtime override supplies `top_p`, the built-in OpenAI-compatible
+client will omit it from the request body rather than serialize `1`.
+
+This establishes the general outbound policy for currently supported optional
+controls:
+
+- `temperature`, `max_tokens`, and `top_p` are omitted when unspecified and
+  included when selected by a profile or runtime override;
+- an explicit numeric zero supplied through a runtime override remains present
+  on the wire through the existing numeric-presence contract;
+- `service_tier` and `reasoning_effort` remain omitted when their resolved
+  values are empty;
+- backend, profile, or runtime `extra_params` remain explicit configuration and
+  are sent when present; and
+- `session_id` remains conditional on a supplied nonempty value, while
+  `response_format` remains conditional on the effective output contract.
+
+The request body will continue to require `model` and `messages`. Endpoint and
+credential resolution remain transport concerns rather than body defaults.
+The positive framework `timeout_seconds` default also remains in place because
+it enforces a Promptkit-owned generation deadline and is not serialized as a
+provider request field.
+
+## Effective Settings And Compatibility
+
+An unspecified numeric provider control continues to use its zero Go value in
+resolved public metadata. For a `GenerateRequest` delivered to an injected
+client, the existing `ExecutionTargetPresence` value distinguishes an explicit
+runtime zero from an inherited unspecified zero. Prepared and inspection
+metadata will continue to report the resolved numeric value without adding
+source-provenance fields.
+
+The behavior change is intentional and belongs in a minor release. Consumers
+that require stable sampling behavior should declare the desired values in
+their profiles or runtime overrides instead of relying on Promptkit to repeat a
+provider's conventional default.
+
+Built-in profile parameters remain explicit profile policy and will continue
+to be sent. An explicit built-in setting will not be removed merely because
+the framework default becomes unspecified.
+
+## Non-Goals
+
+This change does not add:
+
+- pointer-valued numeric fields to file or in-memory profiles;
+- a general provenance model for effective settings;
+- automatic discovery of provider defaults or supported parameters;
+- backend- or model-specific request-shape negotiation;
+- changes to required request fields, structured-output behavior, credentials,
+  or timeout enforcement; or
+- removal of deliberately configured settings from consumer or built-in
+  profiles.
+
+## Target End State
+
+An otherwise unset optional provider tuning parameter is absent from the
+OpenAI-compatible request body. Explicit profile values and runtime overrides,
+including explicit runtime zero values, retain their current precedence and
+wire effect. Promptkit continues to supply only the required protocol fields
+and the settings necessary to honor its own execution and output contracts.
+
+GoDoc, the framework format reference, and the OpenAI-compatible integration
+contract will own the implemented omission and metadata semantics once the
+feature lands.