Clarify context selection policy and hash counts

Author: caioribeiroclw-pixel

docs/gen-ai/gen-ai-events.md

@@ -320,8 +320,8 @@ This event is intended to answer whether an agent run loaded too much context be
 | [`gen_ai.context.selection.selected.count`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | int | The number of context inputs selected for delivery to a GenAI agent or model. [2] | `5` |
 | [`gen_ai.context.selection.suppressed.count`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | int | The number of candidate context inputs intentionally not delivered to a GenAI agent or model. [3] | `13` |
 | [`gen_ai.agent.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` when available | string | The unique identifier of the GenAI agent. | `asst_5j66UpCpwteGg4YSxUnt7lPY` |
-| [`gen_ai.context.selection.delivered_hash.count`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` when delivered hashes are available | int | The number of distinct privacy-preserving delivered-context hashes produced for selected context inputs. [4] | `5` |
-| [`gen_ai.context.selection.reason`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The implementation-specific reason or policy that selected and suppressed context inputs. [5] | `budget`; `relevance` |
+| [`gen_ai.context.selection.delivered_hash.count`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` when delivered hashes are available | int | The number of unique privacy-preserving delivered-context hashes produced for selected context inputs. [4] | `5` |
+| [`gen_ai.context.selection.policy`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The implementation-specific top-level policy or strategy used to select and suppress context inputs. [5] | `budget`; `hybrid_bm25_dense` |
 | [`gen_ai.conversation.id`](/docs/registry/attributes/gen-ai.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` when available | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. | `conv_5j66UpCpwteGg4YSxUnt7lPY` |
 
 **[1] `gen_ai.context.selection.candidate.count`:** This count is intended to help operators detect over-selection without recording raw context content. It SHOULD include inputs discovered before policy, budget, relevance, or deduplication filters are applied.
@@ -330,9 +330,9 @@ This event is intended to answer whether an agent run loaded too much context be
 
 **[3] `gen_ai.context.selection.suppressed.count`:** Suppression may be caused by budget limits, deduplication, policy, target-agent mismatch, relevance filtering, or another implementation-specific reason.
 
-**[4] `gen_ai.context.selection.delivered_hash.count`:** This count lets telemetry report how many delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts.
+**[4] `gen_ai.context.selection.delivered_hash.count`:** This count lets telemetry report how many distinct delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts. It SHOULD count unique hashes, not total hash observations, so duplicate selected inputs can be detected by comparing this value with `gen_ai.context.selection.selected.count`.
 
-**[5] `gen_ai.context.selection.reason`:** The value SHOULD have low cardinality. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `policy`, and `unknown`.
+**[5] `gen_ai.context.selection.policy`:** The value SHOULD have low cardinality and SHOULD describe the top-level selection policy rather than every internal retrieval stage. For hybrid or staged retrieval, use one stable name such as `hybrid_bm25_dense` or `rag_hybrid_v2`; detailed per-stage retrieval telemetry should be reported on retrieval spans or events. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `hybrid_bm25_dense`, and `unknown`.
 
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->

docs/registry/attributes/gen-ai.md

@@ -12,8 +12,8 @@
 | <a id="gen-ai-agent-name" href="#gen-ai-agent-name">`gen_ai.agent.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` |
 | <a id="gen-ai-agent-version" href="#gen-ai-agent-version">`gen_ai.agent.version`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The version of the GenAI agent. | `1.0.0`; `2025-05-01` |
 | <a id="gen-ai-context-selection-candidate-count" href="#gen-ai-context-selection-candidate-count">`gen_ai.context.selection.candidate.count`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of context inputs considered for possible delivery to a GenAI agent or model. [1] | `18` |
-| <a id="gen-ai-context-selection-delivered-hash-count" href="#gen-ai-context-selection-delivered-hash-count">`gen_ai.context.selection.delivered_hash.count`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of distinct privacy-preserving delivered-context hashes produced for selected context inputs. [2] | `5` |
-| <a id="gen-ai-context-selection-reason" href="#gen-ai-context-selection-reason">`gen_ai.context.selection.reason`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The implementation-specific reason or policy that selected and suppressed context inputs. [3] | `budget`; `relevance` |
+| <a id="gen-ai-context-selection-delivered-hash-count" href="#gen-ai-context-selection-delivered-hash-count">`gen_ai.context.selection.delivered_hash.count`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of unique privacy-preserving delivered-context hashes produced for selected context inputs. [2] | `5` |
+| <a id="gen-ai-context-selection-policy" href="#gen-ai-context-selection-policy">`gen_ai.context.selection.policy`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The implementation-specific top-level policy or strategy used to select and suppress context inputs. [3] | `budget`; `hybrid_bm25_dense` |
 | <a id="gen-ai-context-selection-selected-count" href="#gen-ai-context-selection-selected-count">`gen_ai.context.selection.selected.count`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of context inputs selected for delivery to a GenAI agent or model. [4] | `5` |
 | <a id="gen-ai-context-selection-suppressed-count" href="#gen-ai-context-selection-suppressed-count">`gen_ai.context.selection.suppressed.count`</a> | ![Development](https://img.shields.io/badge/-development-blue) | int | The number of candidate context inputs intentionally not delivered to a GenAI agent or model. [5] | `13` |
 | <a id="gen-ai-conversation-id" href="#gen-ai-conversation-id">`gen_ai.conversation.id`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. | `conv_5j66UpCpwteGg4YSxUnt7lPY` |
@@ -71,9 +71,9 @@
 
 **[1] `gen_ai.context.selection.candidate.count`:** This count is intended to help operators detect over-selection without recording raw context content. It SHOULD include inputs discovered before policy, budget, relevance, or deduplication filters are applied.
 
-**[2] `gen_ai.context.selection.delivered_hash.count`:** This count lets telemetry report how many delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts.
+**[2] `gen_ai.context.selection.delivered_hash.count`:** This count lets telemetry report how many distinct delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts. It SHOULD count unique hashes, not total hash observations, so duplicate selected inputs can be detected by comparing this value with `gen_ai.context.selection.selected.count`.
 
-**[3] `gen_ai.context.selection.reason`:** The value SHOULD have low cardinality. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `policy`, and `unknown`.
+**[3] `gen_ai.context.selection.policy`:** The value SHOULD have low cardinality and SHOULD describe the top-level selection policy rather than every internal retrieval stage. For hybrid or staged retrieval, use one stable name such as `hybrid_bm25_dense` or `rag_hybrid_v2`; detailed per-stage retrieval telemetry should be reported on retrieval spans or events. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `hybrid_bm25_dense`, and `unknown`.
 
 **[4] `gen_ai.context.selection.selected.count`:** This count SHOULD represent inputs selected after discovery and filtering, before or at delivery. It does not imply that the selected inputs were decision-relevant.
 

model/gen-ai/events.yaml

@@ -35,7 +35,7 @@ events:
       - ref: gen_ai.context.selection.delivered_hash.count
         requirement_level:
           recommended: when delivered hashes are available
-      - ref: gen_ai.context.selection.reason
+      - ref: gen_ai.context.selection.policy
         requirement_level: recommended
 
   - name: gen_ai.evaluation.result

model/gen-ai/registry.yaml

@@ -518,19 +518,23 @@ attributes:
     stability: development
   - key: gen_ai.context.selection.delivered_hash.count
     type: int
-    brief: The number of distinct privacy-preserving delivered-context hashes produced for selected context inputs.
+    brief: The number of unique privacy-preserving delivered-context hashes produced for selected context inputs.
     note: >
-      This count lets telemetry report how many delivered context identities are available for later correlation
-      without recording raw prompt text, tool output, memory bodies, or repository excerpts.
+      This count lets telemetry report how many distinct delivered context identities are available for later
+      correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts.
+      It SHOULD count unique hashes, not total hash observations, so duplicate selected inputs can be detected by
+      comparing this value with `gen_ai.context.selection.selected.count`.
     examples: [5]
     stability: development
-  - key: gen_ai.context.selection.reason
+  - key: gen_ai.context.selection.policy
     type: string
-    brief: The implementation-specific reason or policy that selected and suppressed context inputs.
+    brief: The implementation-specific top-level policy or strategy used to select and suppress context inputs.
     note: >
-      The value SHOULD have low cardinality. Examples include `budget`, `relevance`, `dedupe`,
-      `target_agent`, `policy`, and `unknown`.
-    examples: ["budget", "relevance"]
+      The value SHOULD have low cardinality and SHOULD describe the top-level selection policy rather than every
+      internal retrieval stage. For hybrid or staged retrieval, use one stable name such as `hybrid_bm25_dense` or
+      `rag_hybrid_v2`; detailed per-stage retrieval telemetry should be reported on retrieval spans or events.
+      Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `hybrid_bm25_dense`, and `unknown`.
+    examples: ["budget", "hybrid_bm25_dense"]
     stability: development
 
   - key: gen_ai.retrieval.documents

schema-snapshot/registry.yaml

@@ -746,25 +746,25 @@ refinements:
       requirement_level: required
       stability: development
       type: int
-    - brief: The number of distinct privacy-preserving delivered-context hashes produced for selected context inputs.
+    - brief: The number of unique privacy-preserving delivered-context hashes produced for selected context inputs.
       examples:
       - 5
       key: gen_ai.context.selection.delivered_hash.count
       note: |
-        This count lets telemetry report how many delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts.
+        This count lets telemetry report how many distinct delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts. It SHOULD count unique hashes, not total hash observations, so duplicate selected inputs can be detected by comparing this value with `gen_ai.context.selection.selected.count`.
       provenance:
         path: ./model/gen-ai/registry.yaml
       requirement_level:
         recommended: when delivered hashes are available
       stability: development
       type: int
-    - brief: The implementation-specific reason or policy that selected and suppressed context inputs.
+    - brief: The implementation-specific top-level policy or strategy used to select and suppress context inputs.
       examples:
       - budget
       - relevance
-      key: gen_ai.context.selection.reason
+      key: gen_ai.context.selection.policy
       note: |
-        The value SHOULD have low cardinality. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `policy`, and `unknown`.
+        The value SHOULD have low cardinality and SHOULD describe the top-level selection policy rather than every internal retrieval stage. For hybrid or staged retrieval, use one stable name such as `hybrid_bm25_dense` or `rag_hybrid_v2`; detailed per-stage retrieval telemetry should be reported on retrieval spans or events. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `hybrid_bm25_dense`, and `unknown`.
       provenance:
         path: ./model/gen-ai/registry.yaml
       requirement_level: recommended
@@ -11934,23 +11934,23 @@ registry:
       path: ./model/gen-ai/registry.yaml
     stability: development
     type: int
-  - brief: The number of distinct privacy-preserving delivered-context hashes produced for selected context inputs.
+  - brief: The number of unique privacy-preserving delivered-context hashes produced for selected context inputs.
     examples:
     - 5
     key: gen_ai.context.selection.delivered_hash.count
     note: |
-      This count lets telemetry report how many delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts.
+      This count lets telemetry report how many distinct delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts. It SHOULD count unique hashes, not total hash observations, so duplicate selected inputs can be detected by comparing this value with `gen_ai.context.selection.selected.count`.
     provenance:
       path: ./model/gen-ai/registry.yaml
     stability: development
     type: int
-  - brief: The implementation-specific reason or policy that selected and suppressed context inputs.
+  - brief: The implementation-specific top-level policy or strategy used to select and suppress context inputs.
     examples:
     - budget
     - relevance
-    key: gen_ai.context.selection.reason
+    key: gen_ai.context.selection.policy
     note: |
-      The value SHOULD have low cardinality. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `policy`, and `unknown`.
+      The value SHOULD have low cardinality and SHOULD describe the top-level selection policy rather than every internal retrieval stage. For hybrid or staged retrieval, use one stable name such as `hybrid_bm25_dense` or `rag_hybrid_v2`; detailed per-stage retrieval telemetry should be reported on retrieval spans or events. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `hybrid_bm25_dense`, and `unknown`.
     provenance:
       path: ./model/gen-ai/registry.yaml
     stability: development
@@ -13812,25 +13812,25 @@ registry:
       requirement_level: required
       stability: development
       type: int
-    - brief: The number of distinct privacy-preserving delivered-context hashes produced for selected context inputs.
+    - brief: The number of unique privacy-preserving delivered-context hashes produced for selected context inputs.
       examples:
       - 5
       key: gen_ai.context.selection.delivered_hash.count
       note: |
-        This count lets telemetry report how many delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts.
+        This count lets telemetry report how many distinct delivered context identities are available for later correlation without recording raw prompt text, tool output, memory bodies, or repository excerpts. It SHOULD count unique hashes, not total hash observations, so duplicate selected inputs can be detected by comparing this value with `gen_ai.context.selection.selected.count`.
       provenance:
         path: ./model/gen-ai/registry.yaml
       requirement_level:
         recommended: when delivered hashes are available
       stability: development
       type: int
-    - brief: The implementation-specific reason or policy that selected and suppressed context inputs.
+    - brief: The implementation-specific top-level policy or strategy used to select and suppress context inputs.
       examples:
       - budget
       - relevance
-      key: gen_ai.context.selection.reason
+      key: gen_ai.context.selection.policy
       note: |
-        The value SHOULD have low cardinality. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `policy`, and `unknown`.
+        The value SHOULD have low cardinality and SHOULD describe the top-level selection policy rather than every internal retrieval stage. For hybrid or staged retrieval, use one stable name such as `hybrid_bm25_dense` or `rag_hybrid_v2`; detailed per-stage retrieval telemetry should be reported on retrieval spans or events. Examples include `budget`, `relevance`, `dedupe`, `target_agent`, `hybrid_bm25_dense`, and `unknown`.
       provenance:
         path: ./model/gen-ai/registry.yaml
       requirement_level: recommended