qati-sdk 1.0.1 → 1.0.3

package/dist/index.js

@@ -634,7 +634,7 @@ var TrustStateResource = class {
   /**
    * Fetches the latest trust state for one entity.
    *
-   * @param entityType - Lowercase entity class: `user`, `device`, `account`, `model`, `session`, or `service` (see {@link EntityTypeLowerCase}).
+   * @param entityType - Lowercase entity class (see {@link EntityTypeLowerCase}).
    * @param entityId - Id for the entity(Required)
    * @param options - Optional contributor limits/window.
    * @returns {@link TrustState} including `current_closure_score`, `risk_tier`, and `top_contributors`.
@@ -655,7 +655,7 @@ var TrustStateResource = class {
   /**
    * Fetches trust states for many entities in one request.
    *
-   * @param entityType - Lowercase entity class: `user`, `device`, `account`, `model`, `session`, or `service` (see {@link EntityTypeLowerCase}).
+   * @param entityType - Lowercase entity class (see {@link EntityTypeLowerCase}).
    * @param entityIds - Distinct ids to query. Prefer length ≤ 100 or the server may reject the request.
    * @param options - Optional contributor limits/window.
    * @returns Array of {@link TrustState} in server-defined order; empty array when `entityIds` is empty.
@@ -822,8 +822,13 @@ var EventPrincipalSchema = z.object({
   device_id: z.string().min(1).optional(),
   session_id: z.string().min(1).optional(),
   model_id: z.string().min(1).optional(),
-  service_id: z.string().min(1).optional()
-});
+  service_id: z.string().min(1).optional(),
+  conversation_id: z.string().min(1).optional(),
+  document_id: z.string().min(1).optional(),
+  tool_id: z.string().min(1).optional(),
+  workflow_id: z.string().min(1).optional(),
+  api_key_id: z.string().min(1).optional()
+}).strict();
 
 // src/v1/schemas/raw-event.ts
 var BaseEventSchema = z.object({
@@ -892,20 +897,26 @@ var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 
 // src/v1/schemas/api-call.ts
 var ApiCallSignalPayloadSchema = z.object({
-  service_id: nonEmptyString(),
-  endpoint: nonEmptyString(),
-  method: z.enum(HTTP_METHODS),
-  status_code: z.number().int().min(100).max(599),
-  authorized: z.boolean().nullable(),
-  authentication_present: z.boolean().nullable().optional(),
-  rate_limited: z.boolean().nullable().optional(),
-  external_side_effect: z.boolean().nullable().optional(),
-  records_returned: z.number().int().nonnegative().nullable().optional(),
-  records_modified: z.number().int().nonnegative().nullable().optional(),
-  contains_sensitive_data: z.boolean().nullable().optional(),
-  latency_ms: z.number().nonnegative().nullable().optional(),
-  retry_count: z.number().int().nonnegative().nullable().optional(),
-  api_key_id: z.string().nullable().optional()
+  service_id: nonEmptyString().describe("Target service identifier."),
+  endpoint: nonEmptyString().describe("API route path."),
+  method: z.enum(HTTP_METHODS).describe("HTTP method: GET, POST, PUT, PATCH, or DELETE."),
+  status_code: z.number().int().min(100).max(599).describe("HTTP response status code."),
+  authorized: z.boolean().nullable().describe(
+    "Whether the call was authorized; null means authorization is unknown."
+  ),
+  authentication_present: z.boolean().nullable().optional().describe(
+    "Whether authentication credentials were present when known."
+  ),
+  rate_limited: z.boolean().nullable().optional().describe("Whether the call was rate limited when known."),
+  external_side_effect: z.boolean().nullable().optional().describe(
+    "Whether the call modifies state outside the caller context when known."
+  ),
+  records_returned: z.number().int().nonnegative().nullable().optional().describe("Number of records returned when available."),
+  records_modified: z.number().int().nonnegative().nullable().optional().describe("Number of records modified when available."),
+  contains_sensitive_data: z.boolean().nullable().optional().describe("Whether sensitive data was involved when known."),
+  latency_ms: z.number().nonnegative().nullable().optional().describe("API latency in milliseconds when available."),
+  retry_count: z.number().int().nonnegative().nullable().optional().describe("Number of retry attempts when available."),
+  api_key_id: z.string().nullable().optional().describe("API key identifier used for the call when applicable.")
 });
 BaseEventSchema.extend({
   signal_payload: ApiCallSignalPayloadSchema
@@ -917,16 +928,16 @@ var createApiCallEvent = (event) => {
   return buildRawEventRequest(event, signalPayload, "API_CALL");
 };
 var AuthSignalPayloadSchema = z.object({
-  result: z.string().nullable().optional(),
-  auth_method: z.string().nullable().optional(),
-  mfa_used: z.boolean().nullable().optional(),
+  result: z.string().nullable().optional().describe("Auth result (SUCCESS, FAILURE)"),
+  auth_method: z.string().nullable().optional().describe("Auth method (PASSWORD, MFA_TOTP, etc.)"),
+  mfa_used: z.boolean().nullable().optional().describe("Whether MFA was used"),
   mfa_bypassed: z.boolean().optional().default(false),
   failed_attempts: z.number().int().nonnegative().optional().default(0),
   ip: z.string().nullable().optional(),
-  country: z.string().nullable().optional(),
+  country: z.string().nullable().optional().describe("ISO 3166-1 alpha-2 country code"),
   user_agent: z.string().nullable().optional(),
   unusual_location: z.boolean().optional().default(false),
-  after_hours_login: z.boolean().optional().default(false)
+  after_hours_login: z.boolean().optional().default(false).describe("Login outside normal business hours")
 });
 BaseEventSchema.extend({
   signal_payload: AuthSignalPayloadSchema
@@ -962,24 +973,50 @@ var CONTEXT_SOURCES = [
 
 // src/v1/schemas/context-integrity.ts
 var ContextIntegritySignalPayloadSchema = z.object({
-  context_source: z.enum(CONTEXT_SOURCES),
-  instruction_conflict_detected: z.boolean(),
-  untrusted_instruction_detected: z.boolean(),
-  context_priority_violation: z.boolean(),
-  recursive_instruction_pattern: z.boolean().optional().default(false),
-  context_drift_score: fraction01Nullable(),
-  system_prompt_conflict_score: fraction01Nullable(),
-  developer_prompt_conflict_score: fraction01Nullable(),
-  retrieved_instruction_count: z.number().int().nonnegative().optional().default(0),
-  hidden_instruction_score: fraction01Nullable(),
-  source_document_id: z.string().nullable().optional(),
-  untrusted_source_count: z.number().int().nonnegative().optional().default(0),
-  source_trust_score: fraction01Nullable(),
-  lowest_source_trust_score: fraction01Nullable(),
-  recursive_pattern_score: fraction01Nullable(),
-  prompt_injection_score: fraction01Nullable(),
-  contains_instruction_override: z.boolean().optional().default(false),
-  context_injection_score: fraction01Nullable()
+  context_source: z.enum(CONTEXT_SOURCES).describe(
+    "Origin of the evaluated context: CONVERSATION_HISTORY, RETRIEVED_DOCUMENT, TOOL_OUTPUT, SYSTEM, DEVELOPER, or USER."
+  ),
+  instruction_conflict_detected: z.boolean().describe("Whether conflicting instructions were detected in context."),
+  untrusted_instruction_detected: z.boolean().describe(
+    "Whether an untrusted source contains instruction-like text."
+  ),
+  context_priority_violation: z.boolean().describe(
+    "Whether lower-priority context attempts to override higher-priority context."
+  ),
+  recursive_instruction_pattern: z.boolean().optional().default(false).describe("Whether the context contains a loop or recursive instruction."),
+  context_drift_score: fraction01Nullable().describe(
+    "0\u20131 context drift score when available."
+  ),
+  system_prompt_conflict_score: fraction01Nullable().describe(
+    "0\u20131 conflict with system prompt intent when available."
+  ),
+  developer_prompt_conflict_score: fraction01Nullable().describe(
+    "0\u20131 conflict with developer prompt intent when available."
+  ),
+  retrieved_instruction_count: z.number().int().nonnegative().optional().default(0).describe("Count of instruction-like snippets in retrieved context."),
+  hidden_instruction_score: fraction01Nullable().describe(
+    "0\u20131 likelihood of hidden instructions when available."
+  ),
+  source_document_id: z.string().nullable().optional().describe("Related document identifier when applicable."),
+  untrusted_source_count: z.number().int().nonnegative().optional().default(0).describe(
+    "Count of untrusted sources; contributes to untrusted-instruction detection."
+  ),
+  source_trust_score: fraction01Nullable().describe(
+    "0\u20131 trust score for the context source when available."
+  ),
+  lowest_source_trust_score: fraction01Nullable().describe(
+    "0\u20131 lowest trust score among sources when available."
+  ),
+  recursive_pattern_score: fraction01Nullable().describe(
+    "0\u20131 recursive pattern score when available."
+  ),
+  prompt_injection_score: fraction01Nullable().describe(
+    "0\u20131 prompt injection score when available; omit if unknown."
+  ),
+  contains_instruction_override: z.boolean().optional().default(false).describe("Whether the context contains an instruction override."),
+  context_injection_score: fraction01Nullable().describe(
+    "0\u20131 context injection score when available; omit if unknown."
+  )
 });
 BaseEventSchema.extend({
   signal_payload: ContextIntegritySignalPayloadSchema
@@ -995,17 +1032,29 @@ var createContextIntegrityEvent = (event) => {
 var ModelOutputSignalPayloadSchema = z.object({
   missing_citations_rate: fraction01Nullable(),
   citation_rate: fraction01Nullable(),
-  expected_citation_rate: fraction01Nullable(),
-  policy_violations: z.number().int().nonnegative().optional().default(0),
+  expected_citation_rate: fraction01Nullable().describe(
+    "Baseline or policy-expected citation rate (use with citation_rate)"
+  ),
+  policy_violations: z.number().int().nonnegative().optional().default(0).describe("Count of policy violations when available."),
   policy_violation_rate: fraction01Nullable(),
   tool_call_inconsistency: fraction01().optional().default(0),
-  tool_inconsistency_rate: fraction01Nullable(),
+  tool_inconsistency_rate: fraction01Nullable().describe(
+    "Rate of inconsistent tool calls in the eval window"
+  ),
   tool_miss_rate: fraction01Nullable(),
-  eval_window_n: z.number().int().min(1).nullable().optional(),
-  hallucination_risk_score: fraction01Nullable(),
-  self_contradiction_score: fraction01Nullable(),
-  grounding_score: fraction01Nullable(),
-  contains_unsupported_claims: z.boolean().optional().default(false)
+  eval_window_n: z.number().int().min(1).nullable().optional().describe("Evaluation window size"),
+  hallucination_risk_score: fraction01Nullable().describe(
+    "0\u20131 hallucination risk when available; omit if unknown."
+  ),
+  self_contradiction_score: fraction01Nullable().describe(
+    "0\u20131 self-contradiction score when available; omit if unknown."
+  ),
+  grounding_score: fraction01Nullable().describe(
+    "0\u20131 grounding score when available; omit if unknown."
+  ),
+  contains_unsupported_claims: z.boolean().optional().default(false).describe(
+    "Whether the output contains unsupported claims; confirm with clients."
+  )
 });
 BaseEventSchema.extend({
   signal_payload: ModelOutputSignalPayloadSchema
@@ -1024,8 +1073,10 @@ var NetworkSignalPayloadSchema = z.object({
   reputation_score: fraction01Nullable(),
   threat_score: fraction01Nullable(),
   is_datacenter: z.boolean().nullable().optional(),
-  is_untrusted_segment: z.boolean().optional().default(false),
-  asn_reputation: fraction01Nullable()
+  is_untrusted_segment: z.boolean().optional().default(false).describe("Traffic originated from an untrusted network segment"),
+  asn_reputation: fraction01Nullable().describe(
+    "Reputation score for the origin ASN (0\u20131, higher is more trusted)"
+  )
 });
 BaseEventSchema.extend({
   signal_payload: NetworkSignalPayloadSchema
@@ -1050,14 +1101,18 @@ var POLICY_RESULTS = ["PASS", "WARN", "FAIL", "BLOCKED"];
 
 // src/v1/schemas/policy-event.ts
 var PolicyEventSignalPayloadSchema = z.object({
-  policy_check_name: nonEmptyString(),
-  policy_category: z.enum(POLICY_CATEGORIES),
-  policy_result: z.enum(POLICY_RESULTS),
-  severity: fraction01(),
-  blocked: z.boolean().optional().default(false),
-  violation_count: z.number().int().nonnegative().optional().default(0),
-  policy_confidence: fraction01Nullable(),
-  redaction_applied: z.boolean().optional().default(false)
+  policy_check_name: nonEmptyString().describe("Name of the policy check."),
+  policy_category: z.enum(POLICY_CATEGORIES).describe(
+    "Policy domain: SAFETY, PRIVACY, SECURITY, COMPLIANCE, CONTENT, or OTHER."
+  ),
+  policy_result: z.enum(POLICY_RESULTS).describe("Policy check result: PASS, WARN, FAIL, or BLOCKED."),
+  severity: fraction01().describe("0\u20131 policy event severity."),
+  blocked: z.boolean().optional().default(false).describe("Whether the action or output was blocked."),
+  violation_count: z.number().int().nonnegative().optional().default(0).describe("Count of policy violations when available."),
+  policy_confidence: fraction01Nullable().describe(
+    "0\u20131 policy classifier confidence when available."
+  ),
+  redaction_applied: z.boolean().optional().default(false).describe("Whether content was redacted.")
 });
 BaseEventSchema.extend({
   signal_payload: PolicyEventSignalPayloadSchema
@@ -1070,18 +1125,30 @@ var createPolicyEvent = (event) => {
   );
   return buildRawEventRequest(event, signalPayload, "POLICY_EVENT");
 };
-var promptHashSchema = z.string().regex(/^[a-fA-F0-9]{64}$/).optional();
+var promptHashSchema = z.string().regex(/^[a-fA-F0-9]{64}$/).optional().describe("Optional SHA-256 hash of prompt text (64 hex characters).");
 var PromptInputSignalPayloadSchema = z.object({
-  prompt_length_chars: z.number().int().nonnegative(),
-  conversation_turn_index: z.number().int().nonnegative(),
-  contains_instruction_override: z.boolean(),
-  contains_tool_request: z.boolean().optional().default(false),
-  contains_secret_request: z.boolean().optional().default(false),
-  contains_policy_challenge: z.boolean().optional().default(false),
-  recursive_pattern_score: fraction01Nullable(),
-  prompt_injection_score: fraction01Nullable(),
-  sensitive_domain: z.boolean().optional().default(false),
-  complexity_score: fraction01Nullable(),
+  prompt_length_chars: z.number().int().nonnegative().describe("Prompt size in characters."),
+  conversation_turn_index: z.number().int().nonnegative().describe("Turn number in the conversation."),
+  contains_instruction_override: z.boolean().describe(
+    "Whether the prompt tries to override prior rules or instructions."
+  ),
+  contains_tool_request: z.boolean().optional().default(false).describe("Whether the prompt requests tool or API execution."),
+  contains_secret_request: z.boolean().optional().default(false).describe(
+    "Whether the prompt requests hidden or confidential information."
+  ),
+  contains_policy_challenge: z.boolean().optional().default(false).describe("Whether the prompt challenges rules, safety, or policy."),
+  recursive_pattern_score: fraction01Nullable().describe(
+    "0\u20131 recursive or looping structure score; omit or null to treat as 0.0."
+  ),
+  prompt_injection_score: fraction01Nullable().describe(
+    "0\u20131 prompt-injection likelihood score; omit or null to treat as 0.0."
+  ),
+  sensitive_domain: z.boolean().optional().default(false).describe(
+    "Whether the prompt targets a sensitive domain (finance, health, legal, cybersecurity, etc.)."
+  ),
+  complexity_score: fraction01Nullable().describe(
+    "0\u20131 prompt complexity or ambiguity score; omit or null to treat as 0.0."
+  ),
   prompt_hash: promptHashSchema
 });
 BaseEventSchema.extend({
@@ -1096,17 +1163,25 @@ var createPromptInputEvent = (event) => {
   return buildRawEventRequest(event, signalPayload, "PROMPT_INPUT");
 };
 var RagRetrievalSignalPayloadSchema = z.object({
-  retriever_id: nonEmptyString(),
-  query_hash: z.string().nullable().optional(),
-  documents_retrieved: z.number().int().nonnegative(),
-  top_k: z.number().int().min(1),
-  average_relevance_score: fraction01(),
-  source_trust_score: fraction01(),
-  lowest_source_trust_score: fraction01Nullable(),
-  untrusted_source_count: z.number().int().nonnegative().optional().default(0),
-  retrieved_context_tokens: z.number().int().nonnegative().optional().default(0),
-  context_injection_score: fraction01().optional().default(0),
-  document_ids: z.array(z.string()).optional().default([])
+  retriever_id: nonEmptyString().describe("Retriever service identifier."),
+  query_hash: z.string().nullable().optional().describe("Hash of the retrieval query when available."),
+  documents_retrieved: z.number().int().nonnegative().describe("Number of documents retrieved."),
+  top_k: z.number().int().min(1).describe("Requested top-k document count."),
+  average_relevance_score: fraction01().describe(
+    "0\u20131 average relevance score across retrieved documents."
+  ),
+  source_trust_score: fraction01().describe(
+    "0\u20131 average trust score across retrieved sources."
+  ),
+  lowest_source_trust_score: fraction01Nullable().describe(
+    "0\u20131 weakest source trust score when available."
+  ),
+  untrusted_source_count: z.number().int().nonnegative().optional().default(0).describe("Count of low-trust or untrusted retrieved sources."),
+  retrieved_context_tokens: z.number().int().nonnegative().optional().default(0).describe("Total retrieved context token count when available."),
+  context_injection_score: fraction01().optional().default(0).describe(
+    "0\u20131 context injection risk score; use 0.0 when unavailable."
+  ),
+  document_ids: z.array(z.string()).optional().default([]).describe("Identifiers for retrieved documents when available.")
 });
 BaseEventSchema.extend({
   signal_payload: RagRetrievalSignalPayloadSchema
@@ -1131,16 +1206,18 @@ var SESSION_STATUSES = [
 
 // src/v1/schemas/session.ts
 var SessionSignalPayloadSchema = z.object({
-  session_status: z.enum(SESSION_STATUSES),
-  session_age_seconds: z.number().nonnegative().optional().default(0),
-  turn_count: z.number().int().nonnegative().optional().default(0),
-  messages_last_minute: z.number().nonnegative().optional().default(0),
-  avg_seconds_between_turns: z.number().nonnegative().nullable().optional(),
-  restart_count_10m: z.number().int().nonnegative().optional().default(0),
-  session_timeout: z.boolean().optional().default(false),
-  abandoned: z.boolean().optional().default(false),
-  conversation_id: z.string().nullable().optional(),
-  user_id: z.string().nullable().optional()
+  session_status: z.enum(SESSION_STATUSES).describe(
+    "Session lifecycle status: STARTED, ACTIVE, ENDED, TIMEOUT, or ABANDONED."
+  ),
+  session_age_seconds: z.number().nonnegative().optional().default(0).describe("Current duration of the session in seconds."),
+  turn_count: z.number().int().nonnegative().optional().default(0).describe("Number of user/model turns in the session."),
+  messages_last_minute: z.number().nonnegative().optional().default(0).describe("Prompt or message rate over the last minute."),
+  avg_seconds_between_turns: z.number().nonnegative().nullable().optional().describe("Average interaction cadence between turns in seconds."),
+  restart_count_10m: z.number().int().nonnegative().optional().default(0).describe("How often the user restarted sessions in the last 10 minutes."),
+  session_timeout: z.boolean().optional().default(false).describe("Whether the session ended due to a timeout."),
+  abandoned: z.boolean().optional().default(false).describe("Whether the session ended abruptly without a clean close."),
+  conversation_id: z.string().nullable().optional().describe("Related conversation identifier when available."),
+  user_id: z.string().nullable().optional().describe("Related user identifier when available.")
 });
 BaseEventSchema.extend({
   signal_payload: SessionSignalPayloadSchema
@@ -1157,11 +1234,19 @@ var SystemTelemetrySignalPayloadSchema = z.object({
   baseline: z.number().nullable().optional(),
   window_seconds: z.number().int().min(1).nullable().optional(),
   error_rate: fraction01().optional().default(0),
-  baseline_error_rate: fraction01Nullable(),
+  baseline_error_rate: fraction01Nullable().describe(
+    "Expected or steady-state error rate (excess over this drives impact)"
+  ),
   unusual_auth_rate: fraction01().optional().default(0),
-  firmware_hash_changed: z.boolean().optional().default(false),
-  expected_hash_match: z.boolean().nullable().optional(),
-  sensor_deviation_score: fraction01Nullable()
+  firmware_hash_changed: z.boolean().optional().default(false).describe(
+    "Device or component firmware hash differs from prior observation"
+  ),
+  expected_hash_match: z.boolean().nullable().optional().describe(
+    "True if hash matched expected; False if mismatch; omit if unknown"
+  ),
+  sensor_deviation_score: fraction01Nullable().describe(
+    "Normalized deviation of sensor readings from baseline"
+  )
 });
 BaseEventSchema.extend({
   signal_payload: SystemTelemetrySignalPayloadSchema
@@ -1189,24 +1274,38 @@ var TOOL_CATEGORIES = [
 
 // src/v1/schemas/tool-call.ts
 var ToolCallSignalPayloadSchema = z.object({
-  tool_name: nonEmptyString(),
-  tool_category: z.enum(TOOL_CATEGORIES),
-  action: nonEmptyString(),
-  authorized: z.boolean().nullable(),
-  safety_critical: z.boolean(),
-  external_side_effect: z.boolean(),
-  tool_call_success: z.boolean().nullable().optional(),
-  latency_ms: z.number().nonnegative().nullable().optional(),
-  error_code: z.string().nullable().optional(),
-  argument_risk_score: fraction01Nullable(),
-  result_size_bytes: z.number().int().nonnegative().nullable().optional(),
-  records_accessed: z.number().int().nonnegative().optional().default(0),
-  contains_sensitive_data: z.boolean().optional().default(false),
-  action_category: z.string().nullable().optional(),
-  method: z.string().nullable().optional(),
-  sensitive_data_involved: z.boolean().optional().default(false),
-  contains_phi: z.boolean().optional().default(false),
-  sensitive_domain: z.boolean().optional().default(false)
+  tool_name: nonEmptyString().describe("Tool identifier."),
+  tool_category: z.enum(TOOL_CATEGORIES).describe(
+    "Tool category: RETRIEVAL, DATABASE, PAYMENT, MESSAGING, CODE_EXECUTION, FILE, EXTERNAL_API, or OTHER."
+  ),
+  action: nonEmptyString().describe("Action attempted by the tool call."),
+  authorized: z.boolean().nullable().describe(
+    "Whether policy allowed the tool call; null means authorization is unknown."
+  ),
+  safety_critical: z.boolean().describe("Whether the call can create serious consequences."),
+  external_side_effect: z.boolean().describe(
+    "Whether the action changes state outside the model context."
+  ),
+  tool_call_success: z.boolean().nullable().optional().describe("Whether the tool call succeeded when known."),
+  latency_ms: z.number().nonnegative().nullable().optional().describe("Tool latency in milliseconds when available."),
+  error_code: z.string().nullable().optional().describe("Error code when the tool call failed."),
+  argument_risk_score: fraction01Nullable().describe(
+    "0\u20131 risk score for tool call arguments when available."
+  ),
+  result_size_bytes: z.number().int().nonnegative().nullable().optional().describe("Size of returned data in bytes when available."),
+  records_accessed: z.number().int().nonnegative().optional().default(0).describe("Number of records touched by the call when available."),
+  contains_sensitive_data: z.boolean().optional().default(false).describe("Whether sensitive data was returned or touched."),
+  action_category: z.string().nullable().optional().describe(
+    "Risk category for the attempted action (e.g. SECURITY, CODE, FINANCIAL, ADMIN) when available."
+  ),
+  method: z.string().nullable().optional().describe("HTTP or RPC method for the tool call when applicable."),
+  sensitive_data_involved: z.boolean().optional().default(false).describe(
+    "Whether sensitive data was involved in the request or result."
+  ),
+  contains_phi: z.boolean().optional().default(false).describe(
+    "Whether protected health information was returned or touched."
+  ),
+  sensitive_domain: z.boolean().optional().default(false).describe("Whether the tool call applies to a sensitive domain.")
 });
 BaseEventSchema.extend({
   signal_payload: ToolCallSignalPayloadSchema
@@ -1218,27 +1317,29 @@ var createToolCallEvent = (event) => {
   return buildRawEventRequest(event, signalPayload, "TOOL_CALL");
 };
 var TransactionSignalPayloadSchema = z.object({
-  amount: z.number().nonnegative().default(0),
-  amount_minor: z.number().int().nonnegative().nullable().optional(),
-  amount_usd: z.number().nonnegative().nullable().optional(),
-  currency: z.string().nullable().optional(),
+  amount: z.number().nonnegative().default(0).describe("Transaction amount in base currency"),
+  amount_minor: z.number().int().nonnegative().nullable().optional().describe("Transaction amount in minor units (e.g. cents)"),
+  amount_usd: z.number().nonnegative().nullable().optional().describe("Transaction amount normalized to USD"),
+  currency: z.string().nullable().optional().describe("ISO 4217 currency code"),
   merchant_category: z.string().nullable().optional(),
   merchant_id: z.string().nullable().optional(),
-  channel: z.string().nullable().optional(),
-  country: z.string().nullable().optional(),
-  velocity: z.number().nonnegative().nullable().optional(),
-  external_anomaly_score: z.number().nullable().optional(),
-  geo_distance: z.number().nonnegative().nullable().optional(),
-  geo_distance_km: z.number().nonnegative().nullable().optional(),
-  records_accessed: z.number().int().nonnegative().nullable().optional(),
-  baseline_records_accessed: z.number().int().nonnegative().nullable().optional(),
-  sensitivity_level: z.string().nullable().optional(),
-  export_count: z.number().int().nonnegative().nullable().optional(),
-  bulk_export: z.boolean().optional().default(false),
-  contains_phi: z.boolean().optional().default(false),
-  control_command: z.string().nullable().optional(),
-  authorized: z.boolean().nullable().optional(),
-  safety_critical: z.boolean().optional().default(false)
+  channel: z.string().nullable().optional().describe("Transaction channel (WEB, MOBILE, ECOM)"),
+  country: z.string().nullable().optional().describe("ISO 3166-1 alpha-2 country code"),
+  velocity: z.number().nonnegative().nullable().optional().describe("Transactions per minute"),
+  external_anomaly_score: z.number().nullable().optional().describe(
+    "Externally supplied anomaly score. When present, bypasses the internal extraction formula and is used directly as raw_value."
+  ),
+  geo_distance: z.number().nonnegative().nullable().optional().describe("Distance in km from usual location"),
+  geo_distance_km: z.number().nonnegative().nullable().optional().describe("Distance in km from usual location"),
+  records_accessed: z.number().int().nonnegative().nullable().optional().describe("Count of records touched in this transaction"),
+  baseline_records_accessed: z.number().int().nonnegative().nullable().optional().describe("Typical or policy baseline record count for comparison"),
+  sensitivity_level: z.string().nullable().optional().describe("Data sensitivity (e.g. LOW, MEDIUM, HIGH)"),
+  export_count: z.number().int().nonnegative().nullable().optional().describe("Number of export operations"),
+  bulk_export: z.boolean().optional().default(false).describe("Whether this is a bulk export"),
+  contains_phi: z.boolean().optional().default(false).describe("Whether exported or accessed data includes PHI"),
+  control_command: z.string().nullable().optional().describe("Issued control or OT command (e.g. VALVE_OPEN)"),
+  authorized: z.boolean().nullable().optional().describe("Whether the action was authorized; omit if unknown"),
+  safety_critical: z.boolean().optional().default(false).describe("Whether the transaction affects safety-critical systems")
 });
 BaseEventSchema.extend({
   signal_payload: TransactionSignalPayloadSchema
@@ -1271,13 +1372,19 @@ var FEEDBACK_ISSUE_TYPES = [
 
 // src/v1/schemas/user-feedback.ts
 var UserFeedbackSignalPayloadSchema = z.object({
-  feedback_type: z.enum(FEEDBACK_TYPES),
-  rating: z.number().nullable().optional(),
-  reported_issue: z.boolean().optional().default(false),
-  issue_type: z.enum(FEEDBACK_ISSUE_TYPES).nullable().optional(),
-  severity: fraction01Nullable(),
-  response_id: z.string().nullable().optional(),
-  user_comment_hash: z.string().nullable().optional()
+  feedback_type: z.enum(FEEDBACK_TYPES).describe(
+    "User feedback category: THUMBS_UP, THUMBS_DOWN, REPORT, CORRECTION, or RATING."
+  ),
+  rating: z.number().nullable().optional().describe("Optional rating in [-1, 1] or on a 1\u20135 scale."),
+  reported_issue: z.boolean().optional().default(false).describe("Whether the user reported a problem."),
+  issue_type: z.enum(FEEDBACK_ISSUE_TYPES).nullable().optional().describe(
+    "Category of the reported issue: hallucination, unsafe, irrelevant, privacy, offensive, or other."
+  ),
+  severity: fraction01Nullable().describe(
+    "0\u20131 user-reported severity when available."
+  ),
+  response_id: z.string().nullable().optional().describe("Identifier of the response being evaluated."),
+  user_comment_hash: z.string().nullable().optional().describe("Hash of optional user comment when available.")
 });
 BaseEventSchema.extend({
   signal_payload: UserFeedbackSignalPayloadSchema
@@ -1312,22 +1419,28 @@ var WORKFLOW_ACTOR_TYPES = ["USER", "AI_AGENT", "SYSTEM"];
 
 // src/v1/schemas/workflow-action.ts
 var WorkflowActionSignalPayloadSchema = z.object({
-  workflow_id: nonEmptyString(),
-  workflow_type: nonEmptyString(),
-  action_name: nonEmptyString(),
-  action_category: z.enum(WORKFLOW_ACTION_CATEGORIES),
-  action_stage: z.enum(WORKFLOW_ACTION_STAGES),
-  actor_type: z.enum(WORKFLOW_ACTOR_TYPES),
-  requires_approval: z.boolean().optional().default(false),
-  approval_present: z.boolean().optional().default(false),
-  external_side_effect: z.boolean().nullable().optional(),
-  safety_critical: z.boolean().nullable().optional(),
-  amount_usd: z.number().nonnegative().nullable().optional(),
-  sensitive_data_involved: z.boolean().optional().default(false),
-  new_counterparty: z.boolean().optional().default(false),
-  is_new_vendor: z.boolean().optional().default(false),
-  is_new_recipient: z.boolean().optional().default(false),
-  is_new_endpoint: z.boolean().optional().default(false)
+  workflow_id: nonEmptyString().describe("Workflow identifier."),
+  workflow_type: nonEmptyString().describe("Type of workflow."),
+  action_name: nonEmptyString().describe("Workflow action attempted."),
+  action_category: z.enum(WORKFLOW_ACTION_CATEGORIES).describe(
+    "Risk category: FINANCIAL, DATA_ACCESS, COMMUNICATION, ADMIN, SECURITY, CODE, or OTHER."
+  ),
+  action_stage: z.enum(WORKFLOW_ACTION_STAGES).describe(
+    "Lifecycle stage: PROPOSED, PRE_EXECUTION, EXECUTED, FAILED, or ROLLED_BACK."
+  ),
+  actor_type: z.enum(WORKFLOW_ACTOR_TYPES).describe("Who initiated the action: USER, AI_AGENT, or SYSTEM."),
+  requires_approval: z.boolean().optional().default(false).describe("Whether approval is required before execution."),
+  approval_present: z.boolean().optional().default(false).describe("Whether required approval is present."),
+  external_side_effect: z.boolean().nullable().optional().describe("Whether the action changes external state when known."),
+  safety_critical: z.boolean().nullable().optional().describe(
+    "Whether the action is safety, security, or business critical when known."
+  ),
+  amount_usd: z.number().nonnegative().nullable().optional().describe("Financial magnitude in USD when applicable."),
+  sensitive_data_involved: z.boolean().optional().default(false).describe("Whether sensitive data was touched."),
+  new_counterparty: z.boolean().optional().default(false).describe("Whether a new vendor, customer, or recipient is involved."),
+  is_new_vendor: z.boolean().optional().default(false).describe("Whether the action involves a new vendor."),
+  is_new_recipient: z.boolean().optional().default(false).describe("Whether the action involves a new recipient."),
+  is_new_endpoint: z.boolean().optional().default(false).describe("Whether the action targets a new endpoint.")
 });
 BaseEventSchema.extend({
   signal_payload: WorkflowActionSignalPayloadSchema