fix: DSC invariant

Author: jan-auer

develop-docs/sdk/telemetry/traces/dynamic-sampling-context.mdx

@@ -49,20 +49,20 @@ To align DSC propagation over all our SDKs, we defined a [unified propagation me
 All of the attributes in the table below are required (non-optional) in a sense, that when they are known to an SDK at the time an envelope with an event (transaction or error) is sent to Sentry, or at the time a baggage header is propagated, they must also be included in said envelope or baggage.
 
 At the moment, only `release`, `environment` and `transaction` are used by the product for dynamic sampling functionality.
-The rest of the context attributes, `trace_id`, `public_key`, `sampled` and `sample_rate`, are used by Relay for internal decisions (like transaction sample rate smoothing).
+The rest of the context attributes, `trace_id`, `public_key`, `sampled` and `sample_rate`, are used by Relay for internal decisions and for extrapolation in the product.
 Additional entries such as `replay_id`, `org` and `sample_rand` are only using the DSC as a means of transport.
 
 | Attribute                   | Type   | Description                                                                                                                  | Example                              | Required Level                       |
 | --------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------------------ |
 | `trace_id`                  | string | The original trace ID as generated by the SDK. This must match the trace id of the submitted transaction item. [1]           | `771a43a4192642f0b136d5159a501700`   | strictly required [0]                |
 | `public_key`                | string | Public key from the DSN used by the SDK. [2]                                                                                 | `49d0f7386ad645858ae85020e393bef3`   | strictly required [0]                |
-| `sample_rate`               | string | The sample rate as defined by the user on the SDK. [3]                                                                       | `0.7`                                | strictly required [0]                |
-| `sampled`                   | string | `"true"` if the trace is sampled, `"false"` otherwise. This is set by the head of the trace.                                 | `true`                               | required                             |
+| `sample_rate`               | string | The sample rate as defined by the user on the SDK. [3] [4]                                                                   | `0.7`                                | strictly required [0]                |
+| `sample_rand`               | string | A truly random number originating from the head of trace SDK. [4]                                                            | `0.5`                                | required                             |
+| `sampled`                   | string | `"true"` if the trace is sampled, `"false"` otherwise. This is set by the head of the trace. [4]                             | `true`                               | required                             |
 | `release`                   | string | The release name as specified in client options.                                                                             | `[email protected]`, `1.2.3`, `2025.4.107` | required                             |
 | `environment`               | string | The environment name as specified in client options.                                                                         | `production`, `staging`              | required                             |
 | `transaction`               | string | The transaction name set on the scope. **Only include** if name has [good quality](#note-on-good-quality-transaction-names). | `/login`, `myApp.myController.login` | required (if known and good quality) |
 | `org`                       | string | The org ID parsed from the DSN or received by a downstream SDK.                                                              | `1`                                  | required                             |
-| `sample_rand`               | string | A truly random number originating from the head of trace SDK.                                                               | `0.5`                                | required                             |
 | `user_segment` [DEPRECATED] | string | User segment as set by the user with `scope.set_user()`.                                                                     |                                      | deprecated                           |
 
 0: In any case, `trace_id`, `public_key`, and `sample_rate` should always be known to an SDK, so these values are strictly required.
@@ -73,6 +73,8 @@ Additional entries such as `replay_id`, `org` and `sample_rand` are only using t
 
 3: This string should always be a number between (and including) 0 and 1 in a notation that is supported by the [JSON specification](https://www.json.org/json-en.html). If a `tracesSampler` callback was used for the sampling decision, its result should be used for `sample_rate` instead of the `tracesSampleRate` from `SentryOptions`. In case `tracesSampler` returns `True` it should be sent as `1.0`, `False` should be sent as `0.0`.
 
+4: These attributes must conform to the invariant `sample_rand < sample_rate <=> sampled`.
+
 <Alert level="warning">
 
 ### Note on good-quality transaction names
@@ -279,5 +281,4 @@ TODO - Add some sort of Q&A section on the following questions, after evaluating
 - Why must baggage be immutable before the second transaction has been started?
 - What are the consequences and impacts of the immutability of baggage on Dynamic Sampling UX?
 - Why can't we just make the decision for the whole trace in Relay after the trace is complete?
-- What is sample rate smoothing and how does it use `sample_rate` from the Dynamic Sampling Context?
 - What are the differences between Dynamic Sampling on traces vs. transactions?