docs: apply reviewer round 11 — correlation families, metadata names

Apply 2 / modify 0 / skip 0, corpus-swept:
- correlation_id two-family wording (protocol hash clusters vs
  governance operation IDs) propagated to webhook-delivery-protocol,
  the correlation page's audit table, and the glossary entry; two
  envelope examples no longer show operator-looking values
  (batch_nightly_*/req_* -> server-shape hash), and the event-payloads
  field row no longer reads as caller-provided
- five remaining metadata examples renamed off the server-managed
  request_id key (SpEL reference, Spring quickstart x2, Python
  quickstart, programmatic how-to x2) -> app_request_id
- verified the remaining "request_id" hits are legitimate server wire
  fields (error bodies, bulk envelopes, event envelope); error-codes
  Correlation identifiers section already correct

Author: amavashev

configuration/spel-expression-reference-for-cycles.md

@@ -34,7 +34,7 @@ Subject fields are evaluated before the guarded method runs, so `#result` is del
 The `metadata` attribute is evaluated after the method returns and must yield a `Map<String, Object>`:
 
 ```java
-@Cycles(value = "1000", metadata = "{'request_id': #requestId, 'model': #result.model}")
+@Cycles(value = "1000", metadata = "{'app_request_id': #requestId, 'model': #result.model}")
 public LlmResponse call(String requestId, String prompt) { ... }
 ```
 

glossary.md

@@ -271,7 +271,7 @@ The W3C Trace Context HTTP header (`00-<trace_id>-<span_id>-<flags>`). Cycles ac
 
 ### correlation_id
 
-A server-set identifier that groups a family of related events in the event stream. Cycles computes it as a deterministic hash over `(tenant_id, scope, action_kind_or_risk_class, window, window_key)` so that threshold-alert → trip → reset chains and `observed_denied` ↔ `reservation.denied` pairs can be joined without an operator supplying anything. Scoped to the event stream only. Distinct from `trace_id` (logical-operation grain, W3C-compatible) and `request_id` (one HTTP request) — both of which are also server-managed but answer different questions.
+A server-set identifier that groups a family of related events in the event stream, in one of two shapes: for protocol event-stream clusters, a deterministic hash over `(tenant_id, scope, action_kind_or_risk_class, window, window_key)` — so threshold-alert → trip → reset chains and `observed_denied` ↔ `reservation.denied` pairs join without an operator supplying anything; for governance/admin operations, an explicit server-composed operation ID (e.g. `webhook_create:<id>`, `webhook_bulk_action:<action>:<request_id>`, tenant-cascade IDs). Scoped to the event stream only. Distinct from `trace_id` (logical-operation grain, W3C-compatible) and `request_id` (one HTTP request) — both of which are also server-managed but answer different questions.
 
 ## Admin Plane
 

how-to/using-the-cycles-client-programmatically.md

@@ -163,7 +163,7 @@ client.commit_reservation(reservation_id, CommitRequest(
         latency_ms=320,
         model_version="gpt-4o-2024-08-06",
     ),
-    metadata={"request_id": "req-abc-123"},
+    metadata={"app_request_id": "req-abc-123"},
 ))
 ```
 ```java [Java]
@@ -177,7 +177,7 @@ CommitRequest commitRequest = CommitRequest.builder()
     .idempotencyKey("commit-" + UUID.randomUUID())
     .actual(new Amount(Unit.USD_MICROCENTS, 3200L))
     .metrics(metrics)
-    .metadata(Map.of("request_id", "req-abc-123"))
+    .metadata(Map.of("app_request_id", "req-abc-123"))
     .build();
 
 CyclesResponse<Map<String, Object>> commitResponse =

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

@@ -84,7 +84,7 @@ Standard event payloads carry:
 |---|---|
 | `request_id` | Populated on every event causally downstream of an HTTP request — including async and queued work that spans thread / process boundaries. Pre-v0.1.25 events may lack it. |
 | `trace_id` | OPTIONAL on the schema; populated by conformant v0.1.25.14+ runtime servers. |
-| `correlation_id` | Server-set: a deterministic hash over `(tenant_id, scope, action_kind_or_risk_class, window, window_key)`. Groups related events in the stream. |
+| `correlation_id` | Server-set, two shapes: a deterministic hash over `(tenant_id, scope, action_kind_or_risk_class, window, window_key)` for protocol event-stream clusters, or an explicit operation ID (`webhook_create:<id>`, `webhook_bulk_action:<action>:<request_id>`, cascade IDs) for governance/admin operations. Groups related events in the stream. |
 
 ### Inside audit-log entries
 

protocol/event-payloads-reference.md

@@ -46,7 +46,7 @@ Every event shares this envelope structure. The `data` field varies by event typ
     "source_ip": "10.0.1.50"
   },
   "data": { },
-  "correlation_id": "req_789",
+  "correlation_id": "3f2a9c14e0b7d5a1",
   "request_id": "req_789",
   "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
   "metadata": {}
@@ -66,7 +66,7 @@ Every event shares this envelope structure. The `data` field varies by event typ
 | `source` | string | Yes | Emitting service: `cycles-server` (runtime events), `cycles-admin` (admin-plane events including bulk-action emits and webhook lifecycle events since v0.1.25.38/.39), or `cycles-events` (dispatcher-emitted `webhook.disabled` on auto-disable, v0.1.25.11). |
 | `actor` | object | When applicable | Who triggered: `type` (`api_key`, `admin`, `system`, `scheduler`), `key_id`, `source_ip` |
 | `data` | object | Varies | Event-specific payload (see below). Some events emit `null`. |
-| `correlation_id` | string | When provided | Links related events across a workflow |
+| `correlation_id` | string | When applicable | Server-set family key — deterministic hash for event-stream clusters, explicit operation IDs (`webhook_create:<id>` etc.) for admin operations |
 | `request_id` | string | When provided | From `X-Request-Id` header on originating request |
 | `trace_id` | string | When provided | W3C Trace Context-compatible correlation identifier (32 lowercase hex characters). Links the event to the originating request, its audit entry, and sibling events within the same logical operation. |
 | `metadata` | object | When provided | Operator-defined key-value pairs |

protocol/webhook-event-delivery-protocol.md

@@ -51,7 +51,7 @@ The body is a JSON-serialized Event object:
     "remaining": 0,
     "spent": 10000
   },
-  "correlation_id": "batch_nightly_2026_04_18",
+  "correlation_id": "3f2a9c14e0b7d5a1",
   "request_id": "req_789",
   "trace_id": "0af7651916cd43dd8448eb211c80319c",
   "metadata": {}
@@ -60,7 +60,7 @@ The body is a JSON-serialized Event object:
 
 Fields `scope`, `actor`, `data`, `correlation_id`, `request_id`, `trace_id`, and `metadata` are optional (omitted when null).
 
-**Correlation fields.** `request_id` narrows to one HTTP request; `trace_id` (32-hex W3C) narrows to one logical operation (may span many requests); `correlation_id` is operator-populated and groups a family of related events. See [Correlation and Tracing](/protocol/correlation-and-tracing-in-cycles).
+**Correlation fields.** `request_id` narrows to one HTTP request; `trace_id` (32-hex W3C) narrows to one logical operation (may span many requests); `correlation_id` groups a family of related events — it is server-set in one of two shapes: a deterministic hash over `(tenant_id, scope, action_kind_or_risk_class, window, window_key)` for protocol event-stream clusters, or an explicit operation ID (e.g. `webhook_create:<id>`, `webhook_bulk_action:<action>:<request_id>`) for governance/admin operations. See [Correlation and Tracing](/protocol/correlation-and-tracing-in-cycles).
 
 ## Event types (47)
 

quickstart/getting-started-with-the-cycles-spring-boot-starter.md

@@ -394,7 +394,7 @@ Evaluates the reservation without actually holding budget. The guarded method do
 ### Commit metadata
 
 ```java
-@Cycles(value = "1000", metadata = "{'request_id': #requestId, 'model': #result.model}")
+@Cycles(value = "1000", metadata = "{'app_request_id': #requestId, 'model': #result.model}")
 ```
 
 Since 0.2.5. The `metadata` SpEL expression is evaluated after the method returns — `#result` is available — and must yield a `Map<String, Object>`. The result is merged with metadata set programmatically via `CyclesContextHolder`; programmatic metadata wins on key conflicts.
@@ -435,7 +435,7 @@ public String process(String input) {
     ctx.setMetrics(metrics);
 
     // Attach metadata for audit
-    ctx.setCommitMetadata(Map.of("request_id", "req-abc-123"));
+    ctx.setCommitMetadata(Map.of("app_request_id", "req-abc-123"));
 
     return chatModel.call(input);
 }

quickstart/getting-started-with-the-python-client.md

@@ -209,7 +209,7 @@ def process(text: str) -> str:
     )
 
     # Attach metadata for audit
-    ctx.commit_metadata = {"request_id": "req-abc-123"}
+    ctx.commit_metadata = {"app_request_id": "req-abc-123"}
 
     return call_llm(text)
 ```