docs: apply reviewer round 10 — correlation-id family consistency

Apply 3 / modify 0 / skip 0:
- standard-metrics: lifecycle steps and Python/Java snippets no longer
  attach metadata under the server-managed names (renamed to
  app_request_id / external_trace_id, matching the page's own best
  practice); correlation-and-tracing warning box and the glossary
  trace_id entry now teach the distinct-name convention instead of
  blessing metadata.trace_id
- correlation-and-tracing: correlation_id described as two server-set
  families - deterministic hash for protocol event-stream clusters,
  explicit operation IDs (webhook_create:<id>,
  webhook_bulk_action:<action>:<request_id>) for governance/admin
  events, per the event-payloads reference
- dashboard Events page: correlation_id/request_id descriptors fixed
  (event-stream cluster / originating HTTP request - was
  "request-scoped"/"hop-scoped")

Author: amavashev

glossary.md

@@ -263,7 +263,7 @@ A server-generated identifier unique to one HTTP request. Appears in every `Erro
 
 ### trace_id
 
-A 32-hex-character W3C Trace Context-compatible identifier for a logical operation that may span many HTTP requests. Derived from inbound `traceparent` (when valid) → `X-Cycles-Trace-Id` (when valid) → server-generated. Echoed on every response as the `X-Cycles-Trace-Id` header and carried on webhook deliveries, events, audit rows, and (as of governance-admin v0.1.25.28) on `WebhookDelivery` schema fields. Introduced across the stack on 2026-04-18 (cycles-server v0.1.25.14, cycles-server-admin v0.1.25.31, cycles-server-events v0.1.25.7). Distinct from the application-level `metadata.trace_id` documented in [Standard Metrics and Metadata](/protocol/standard-metrics-and-metadata-in-cycles) (that one is operator-free-form; this one is server-managed W3C). See [Correlation and Tracing](/protocol/correlation-and-tracing-in-cycles).
+A 32-hex-character W3C Trace Context-compatible identifier for a logical operation that may span many HTTP requests. Derived from inbound `traceparent` (when valid) → `X-Cycles-Trace-Id` (when valid) → server-generated. Echoed on every response as the `X-Cycles-Trace-Id` header and carried on webhook deliveries, events, audit rows, and (as of governance-admin v0.1.25.28) on `WebhookDelivery` schema fields. Introduced across the stack on 2026-04-18 (cycles-server v0.1.25.14, cycles-server-admin v0.1.25.31, cycles-server-events v0.1.25.7). Distinct from application-level correlation keys in `metadata` (name those `external_trace_id` or similar — see [Standard Metrics and Metadata](/protocol/standard-metrics-and-metadata-in-cycles); this one is server-managed W3C). See [Correlation and Tracing](/protocol/correlation-and-tracing-in-cycles).
 
 ### traceparent
 

how-to/using-the-cycles-dashboard.md

@@ -183,7 +183,7 @@ Force-release uses dual authentication — the dashboard's nginx routes `/v1/res
 
 The Events page is correlation-first, not time-first:
 
-- Every row has a `correlation_id` (request-scoped) and `request_id` (hop-scoped). Clicking either filters to the full graph of related events across budgets, reservations, webhooks, and audit.
+- Every row has a `correlation_id` (event-stream cluster — groups related events like threshold → trip → reset chains or one admin operation's fan-out) and `request_id` (the originating HTTP request). Clicking either filters to the full graph of related events across budgets, reservations, webhooks, and audit.
 - Expandable detail rows show the full event payload — including `data`, `actor`, `metadata`, and delivery outcome if the event went out over a webhook.
 - Filters: event type, category, tenant, scope, time range, correlation ID.
 

protocol/correlation-and-tracing-in-cycles.md

@@ -21,10 +21,10 @@ Cycles carries three correlation identifiers, each with a different grain.
 
 - **`request_id`** is server-generated for every inbound HTTP request. It appears in every error response, audit-log entry, and event that is causally downstream of that request. Use it to correlate the side effects of one specific HTTP call.
 - **`trace_id`** identifies a logical operation that may cross several HTTP boundaries (for example: a client's reserve → multiple provider retries → commit). It is a 32-hex-character W3C Trace Context-compatible identifier. Use it to reconstruct the full operation across planes.
-- **`correlation_id`** is set by the server — a deterministic hash over `(tenant_id, scope, action_kind_or_risk_class, window, window_key)`. Because the hash is deterministic, every event produced for the same tenant/scope/kind/window cluster carries the same value, which is what lets you JOIN threshold-alert → trip → reset chains and `observed_denied` ↔ `reservation.denied` pairs. It is scoped to the event stream only — it does not appear on responses or audit rows.
+- **`correlation_id`** is set by the server, in one of two shapes depending on the emitting plane. **Protocol event-stream clusters** use a deterministic hash over `(tenant_id, scope, action_kind_or_risk_class, window, window_key)` — every event for the same cluster carries the same value, which is what lets you JOIN threshold-alert → trip → reset chains and `observed_denied` ↔ `reservation.denied` pairs. **Governance/admin operations** (lifecycle, bulk actions, webhook management, tenant-close cascades) use explicit server-composed operation IDs such as `webhook_create:<id>` or `webhook_bulk_action:<action>:<request_id>` — see the [event payload reference](/protocol/event-payloads-reference) for the shapes. Either way it is scoped to the event stream only — it does not appear on responses or audit rows.
 
 ::: warning Don't confuse with `metadata.trace_id`
-[Standard Metrics and Metadata](/protocol/standard-metrics-and-metadata-in-cycles) documents an application-level `metadata.trace_id` that callers can put in the `metadata` map on commits and events. That is a free-form string the server stores but does not interpret. The `trace_id` described on this page is the separate, server-managed 32-hex W3C identifier that flows on response headers, error bodies, events, audit rows, and webhook deliveries. They can coexist: the application `metadata.trace_id` is useful for joining Cycles data with your own distributed tracing, while the server `trace_id` joins across Cycles planes.
+[Standard Metrics and Metadata](/protocol/standard-metrics-and-metadata-in-cycles) documents application-level correlation keys that callers can put in the `metadata` map on commits and events — free-form strings the server stores but does not interpret. Name them distinctly (e.g. `external_trace_id`, `app_request_id`) rather than reusing `trace_id`/`request_id`, which are the server-managed identifiers described on this page (32-hex W3C, flowing on response headers, error bodies, events, audit rows, and webhook deliveries). The two coexist: your `metadata.external_trace_id` joins Cycles data with your own distributed tracing, while the server `trace_id` joins across Cycles planes.
 :::
 
 ## Inbound header precedence

protocol/standard-metrics-and-metadata-in-cycles.md

@@ -140,9 +140,9 @@ Metadata is accepted on several other operations beyond commits and events:
 
 This means a full reservation lifecycle can carry metadata from creation through commit:
 
-1. Create reservation with `metadata: { "trace_id": "..." }`
+1. Create reservation with `metadata: { "external_trace_id": "..." }`
 2. Extend with `metadata: { "heartbeat_seq": "3" }`
-3. Commit with `metadata: { "request_id": "..." }` and `metrics: { ... }`
+3. Commit with `metadata: { "app_request_id": "..." }` and `metrics: { ... }`
 
 Commit metadata is preserved on the reservation and returned by `GET /v1/reservations/{id}` as `committed_metadata` — distinct from the reserve-time `metadata` field, which is returned on the same response — so the metadata attached at reserve and commit time is auditable after the fact, not just sent and forgotten.
 
@@ -166,8 +166,8 @@ def chat(prompt: str) -> str:
         model_version=response.model,
     )
     ctx.commit_metadata = {
-        "request_id": request_id,
-        "trace_id": trace_id,
+        "app_request_id": app_request_id,
+        "external_trace_id": otel_trace_id,
     }
 
     return response.text
@@ -187,8 +187,8 @@ public ChatResponse chat(String prompt) {
     ctx.setMetrics(metrics);
 
     ctx.setCommitMetadata(Map.of(
-        "request_id", requestId,
-        "trace_id", traceId
+        "app_request_id", appRequestId,
+        "external_trace_id", otelTraceId
     ));
 
     return response;