qati-sdk 1.0.2 → 1.0.3

package/dist/index.cjs

@@ -903,20 +903,26 @@ var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 
 // src/v1/schemas/api-call.ts
 var ApiCallSignalPayloadSchema = zod.z.object({
-  service_id: nonEmptyString(),
-  endpoint: nonEmptyString(),
-  method: zod.z.enum(HTTP_METHODS),
-  status_code: zod.z.number().int().min(100).max(599),
-  authorized: zod.z.boolean().nullable(),
-  authentication_present: zod.z.boolean().nullable().optional(),
-  rate_limited: zod.z.boolean().nullable().optional(),
-  external_side_effect: zod.z.boolean().nullable().optional(),
-  records_returned: zod.z.number().int().nonnegative().nullable().optional(),
-  records_modified: zod.z.number().int().nonnegative().nullable().optional(),
-  contains_sensitive_data: zod.z.boolean().nullable().optional(),
-  latency_ms: zod.z.number().nonnegative().nullable().optional(),
-  retry_count: zod.z.number().int().nonnegative().nullable().optional(),
-  api_key_id: zod.z.string().nullable().optional()
+  service_id: nonEmptyString().describe("Target service identifier."),
+  endpoint: nonEmptyString().describe("API route path."),
+  method: zod.z.enum(HTTP_METHODS).describe("HTTP method: GET, POST, PUT, PATCH, or DELETE."),
+  status_code: zod.z.number().int().min(100).max(599).describe("HTTP response status code."),
+  authorized: zod.z.boolean().nullable().describe(
+    "Whether the call was authorized; null means authorization is unknown."
+  ),
+  authentication_present: zod.z.boolean().nullable().optional().describe(
+    "Whether authentication credentials were present when known."
+  ),
+  rate_limited: zod.z.boolean().nullable().optional().describe("Whether the call was rate limited when known."),
+  external_side_effect: zod.z.boolean().nullable().optional().describe(
+    "Whether the call modifies state outside the caller context when known."
+  ),
+  records_returned: zod.z.number().int().nonnegative().nullable().optional().describe("Number of records returned when available."),
+  records_modified: zod.z.number().int().nonnegative().nullable().optional().describe("Number of records modified when available."),
+  contains_sensitive_data: zod.z.boolean().nullable().optional().describe("Whether sensitive data was involved when known."),
+  latency_ms: zod.z.number().nonnegative().nullable().optional().describe("API latency in milliseconds when available."),
+  retry_count: zod.z.number().int().nonnegative().nullable().optional().describe("Number of retry attempts when available."),
+  api_key_id: zod.z.string().nullable().optional().describe("API key identifier used for the call when applicable.")
 });
 BaseEventSchema.extend({
   signal_payload: ApiCallSignalPayloadSchema
@@ -928,16 +934,16 @@ var createApiCallEvent = (event) => {
   return buildRawEventRequest(event, signalPayload, "API_CALL");
 };
 var AuthSignalPayloadSchema = zod.z.object({
-  result: zod.z.string().nullable().optional(),
-  auth_method: zod.z.string().nullable().optional(),
-  mfa_used: zod.z.boolean().nullable().optional(),
+  result: zod.z.string().nullable().optional().describe("Auth result (SUCCESS, FAILURE)"),
+  auth_method: zod.z.string().nullable().optional().describe("Auth method (PASSWORD, MFA_TOTP, etc.)"),
+  mfa_used: zod.z.boolean().nullable().optional().describe("Whether MFA was used"),
   mfa_bypassed: zod.z.boolean().optional().default(false),
   failed_attempts: zod.z.number().int().nonnegative().optional().default(0),
   ip: zod.z.string().nullable().optional(),
-  country: zod.z.string().nullable().optional(),
+  country: zod.z.string().nullable().optional().describe("ISO 3166-1 alpha-2 country code"),
   user_agent: zod.z.string().nullable().optional(),
   unusual_location: zod.z.boolean().optional().default(false),
-  after_hours_login: zod.z.boolean().optional().default(false)
+  after_hours_login: zod.z.boolean().optional().default(false).describe("Login outside normal business hours")
 });
 BaseEventSchema.extend({
   signal_payload: AuthSignalPayloadSchema
@@ -973,24 +979,50 @@ var CONTEXT_SOURCES = [
 
 // src/v1/schemas/context-integrity.ts
 var ContextIntegritySignalPayloadSchema = zod.z.object({
-  context_source: zod.z.enum(CONTEXT_SOURCES),
-  instruction_conflict_detected: zod.z.boolean(),
-  untrusted_instruction_detected: zod.z.boolean(),
-  context_priority_violation: zod.z.boolean(),
-  recursive_instruction_pattern: zod.z.boolean().optional().default(false),
-  context_drift_score: fraction01Nullable(),
-  system_prompt_conflict_score: fraction01Nullable(),
-  developer_prompt_conflict_score: fraction01Nullable(),
-  retrieved_instruction_count: zod.z.number().int().nonnegative().optional().default(0),
-  hidden_instruction_score: fraction01Nullable(),
-  source_document_id: zod.z.string().nullable().optional(),
-  untrusted_source_count: zod.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: zod.z.boolean().optional().default(false),
-  context_injection_score: fraction01Nullable()
+  context_source: zod.z.enum(CONTEXT_SOURCES).describe(
+    "Origin of the evaluated context: CONVERSATION_HISTORY, RETRIEVED_DOCUMENT, TOOL_OUTPUT, SYSTEM, DEVELOPER, or USER."
+  ),
+  instruction_conflict_detected: zod.z.boolean().describe("Whether conflicting instructions were detected in context."),
+  untrusted_instruction_detected: zod.z.boolean().describe(
+    "Whether an untrusted source contains instruction-like text."
+  ),
+  context_priority_violation: zod.z.boolean().describe(
+    "Whether lower-priority context attempts to override higher-priority context."
+  ),
+  recursive_instruction_pattern: zod.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: zod.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: zod.z.string().nullable().optional().describe("Related document identifier when applicable."),
+  untrusted_source_count: zod.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: zod.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
@@ -1006,17 +1038,29 @@ var createContextIntegrityEvent = (event) => {
 var ModelOutputSignalPayloadSchema = zod.z.object({
   missing_citations_rate: fraction01Nullable(),
   citation_rate: fraction01Nullable(),
-  expected_citation_rate: fraction01Nullable(),
-  policy_violations: zod.z.number().int().nonnegative().optional().default(0),
+  expected_citation_rate: fraction01Nullable().describe(
+    "Baseline or policy-expected citation rate (use with citation_rate)"
+  ),
+  policy_violations: zod.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: zod.z.number().int().min(1).nullable().optional(),
-  hallucination_risk_score: fraction01Nullable(),
-  self_contradiction_score: fraction01Nullable(),
-  grounding_score: fraction01Nullable(),
-  contains_unsupported_claims: zod.z.boolean().optional().default(false)
+  eval_window_n: zod.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: zod.z.boolean().optional().default(false).describe(
+    "Whether the output contains unsupported claims; confirm with clients."
+  )
 });
 BaseEventSchema.extend({
   signal_payload: ModelOutputSignalPayloadSchema
@@ -1035,8 +1079,10 @@ var NetworkSignalPayloadSchema = zod.z.object({
   reputation_score: fraction01Nullable(),
   threat_score: fraction01Nullable(),
   is_datacenter: zod.z.boolean().nullable().optional(),
-  is_untrusted_segment: zod.z.boolean().optional().default(false),
-  asn_reputation: fraction01Nullable()
+  is_untrusted_segment: zod.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
@@ -1061,14 +1107,18 @@ var POLICY_RESULTS = ["PASS", "WARN", "FAIL", "BLOCKED"];
 
 // src/v1/schemas/policy-event.ts
 var PolicyEventSignalPayloadSchema = zod.z.object({
-  policy_check_name: nonEmptyString(),
-  policy_category: zod.z.enum(POLICY_CATEGORIES),
-  policy_result: zod.z.enum(POLICY_RESULTS),
-  severity: fraction01(),
-  blocked: zod.z.boolean().optional().default(false),
-  violation_count: zod.z.number().int().nonnegative().optional().default(0),
-  policy_confidence: fraction01Nullable(),
-  redaction_applied: zod.z.boolean().optional().default(false)
+  policy_check_name: nonEmptyString().describe("Name of the policy check."),
+  policy_category: zod.z.enum(POLICY_CATEGORIES).describe(
+    "Policy domain: SAFETY, PRIVACY, SECURITY, COMPLIANCE, CONTENT, or OTHER."
+  ),
+  policy_result: zod.z.enum(POLICY_RESULTS).describe("Policy check result: PASS, WARN, FAIL, or BLOCKED."),
+  severity: fraction01().describe("0\u20131 policy event severity."),
+  blocked: zod.z.boolean().optional().default(false).describe("Whether the action or output was blocked."),
+  violation_count: zod.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: zod.z.boolean().optional().default(false).describe("Whether content was redacted.")
 });
 BaseEventSchema.extend({
   signal_payload: PolicyEventSignalPayloadSchema
@@ -1081,18 +1131,30 @@ var createPolicyEvent = (event) => {
   );
   return buildRawEventRequest(event, signalPayload, "POLICY_EVENT");
 };
-var promptHashSchema = zod.z.string().regex(/^[a-fA-F0-9]{64}$/).optional();
+var promptHashSchema = zod.z.string().regex(/^[a-fA-F0-9]{64}$/).optional().describe("Optional SHA-256 hash of prompt text (64 hex characters).");
 var PromptInputSignalPayloadSchema = zod.z.object({
-  prompt_length_chars: zod.z.number().int().nonnegative(),
-  conversation_turn_index: zod.z.number().int().nonnegative(),
-  contains_instruction_override: zod.z.boolean(),
-  contains_tool_request: zod.z.boolean().optional().default(false),
-  contains_secret_request: zod.z.boolean().optional().default(false),
-  contains_policy_challenge: zod.z.boolean().optional().default(false),
-  recursive_pattern_score: fraction01Nullable(),
-  prompt_injection_score: fraction01Nullable(),
-  sensitive_domain: zod.z.boolean().optional().default(false),
-  complexity_score: fraction01Nullable(),
+  prompt_length_chars: zod.z.number().int().nonnegative().describe("Prompt size in characters."),
+  conversation_turn_index: zod.z.number().int().nonnegative().describe("Turn number in the conversation."),
+  contains_instruction_override: zod.z.boolean().describe(
+    "Whether the prompt tries to override prior rules or instructions."
+  ),
+  contains_tool_request: zod.z.boolean().optional().default(false).describe("Whether the prompt requests tool or API execution."),
+  contains_secret_request: zod.z.boolean().optional().default(false).describe(
+    "Whether the prompt requests hidden or confidential information."
+  ),
+  contains_policy_challenge: zod.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: zod.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({
@@ -1107,17 +1169,25 @@ var createPromptInputEvent = (event) => {
   return buildRawEventRequest(event, signalPayload, "PROMPT_INPUT");
 };
 var RagRetrievalSignalPayloadSchema = zod.z.object({
-  retriever_id: nonEmptyString(),
-  query_hash: zod.z.string().nullable().optional(),
-  documents_retrieved: zod.z.number().int().nonnegative(),
-  top_k: zod.z.number().int().min(1),
-  average_relevance_score: fraction01(),
-  source_trust_score: fraction01(),
-  lowest_source_trust_score: fraction01Nullable(),
-  untrusted_source_count: zod.z.number().int().nonnegative().optional().default(0),
-  retrieved_context_tokens: zod.z.number().int().nonnegative().optional().default(0),
-  context_injection_score: fraction01().optional().default(0),
-  document_ids: zod.z.array(zod.z.string()).optional().default([])
+  retriever_id: nonEmptyString().describe("Retriever service identifier."),
+  query_hash: zod.z.string().nullable().optional().describe("Hash of the retrieval query when available."),
+  documents_retrieved: zod.z.number().int().nonnegative().describe("Number of documents retrieved."),
+  top_k: zod.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: zod.z.number().int().nonnegative().optional().default(0).describe("Count of low-trust or untrusted retrieved sources."),
+  retrieved_context_tokens: zod.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: zod.z.array(zod.z.string()).optional().default([]).describe("Identifiers for retrieved documents when available.")
 });
 BaseEventSchema.extend({
   signal_payload: RagRetrievalSignalPayloadSchema
@@ -1142,16 +1212,18 @@ var SESSION_STATUSES = [
 
 // src/v1/schemas/session.ts
 var SessionSignalPayloadSchema = zod.z.object({
-  session_status: zod.z.enum(SESSION_STATUSES),
-  session_age_seconds: zod.z.number().nonnegative().optional().default(0),
-  turn_count: zod.z.number().int().nonnegative().optional().default(0),
-  messages_last_minute: zod.z.number().nonnegative().optional().default(0),
-  avg_seconds_between_turns: zod.z.number().nonnegative().nullable().optional(),
-  restart_count_10m: zod.z.number().int().nonnegative().optional().default(0),
-  session_timeout: zod.z.boolean().optional().default(false),
-  abandoned: zod.z.boolean().optional().default(false),
-  conversation_id: zod.z.string().nullable().optional(),
-  user_id: zod.z.string().nullable().optional()
+  session_status: zod.z.enum(SESSION_STATUSES).describe(
+    "Session lifecycle status: STARTED, ACTIVE, ENDED, TIMEOUT, or ABANDONED."
+  ),
+  session_age_seconds: zod.z.number().nonnegative().optional().default(0).describe("Current duration of the session in seconds."),
+  turn_count: zod.z.number().int().nonnegative().optional().default(0).describe("Number of user/model turns in the session."),
+  messages_last_minute: zod.z.number().nonnegative().optional().default(0).describe("Prompt or message rate over the last minute."),
+  avg_seconds_between_turns: zod.z.number().nonnegative().nullable().optional().describe("Average interaction cadence between turns in seconds."),
+  restart_count_10m: zod.z.number().int().nonnegative().optional().default(0).describe("How often the user restarted sessions in the last 10 minutes."),
+  session_timeout: zod.z.boolean().optional().default(false).describe("Whether the session ended due to a timeout."),
+  abandoned: zod.z.boolean().optional().default(false).describe("Whether the session ended abruptly without a clean close."),
+  conversation_id: zod.z.string().nullable().optional().describe("Related conversation identifier when available."),
+  user_id: zod.z.string().nullable().optional().describe("Related user identifier when available.")
 });
 BaseEventSchema.extend({
   signal_payload: SessionSignalPayloadSchema
@@ -1168,11 +1240,19 @@ var SystemTelemetrySignalPayloadSchema = zod.z.object({
   baseline: zod.z.number().nullable().optional(),
   window_seconds: zod.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: zod.z.boolean().optional().default(false),
-  expected_hash_match: zod.z.boolean().nullable().optional(),
-  sensor_deviation_score: fraction01Nullable()
+  firmware_hash_changed: zod.z.boolean().optional().default(false).describe(
+    "Device or component firmware hash differs from prior observation"
+  ),
+  expected_hash_match: zod.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
@@ -1200,24 +1280,38 @@ var TOOL_CATEGORIES = [
 
 // src/v1/schemas/tool-call.ts
 var ToolCallSignalPayloadSchema = zod.z.object({
-  tool_name: nonEmptyString(),
-  tool_category: zod.z.enum(TOOL_CATEGORIES),
-  action: nonEmptyString(),
-  authorized: zod.z.boolean().nullable(),
-  safety_critical: zod.z.boolean(),
-  external_side_effect: zod.z.boolean(),
-  tool_call_success: zod.z.boolean().nullable().optional(),
-  latency_ms: zod.z.number().nonnegative().nullable().optional(),
-  error_code: zod.z.string().nullable().optional(),
-  argument_risk_score: fraction01Nullable(),
-  result_size_bytes: zod.z.number().int().nonnegative().nullable().optional(),
-  records_accessed: zod.z.number().int().nonnegative().optional().default(0),
-  contains_sensitive_data: zod.z.boolean().optional().default(false),
-  action_category: zod.z.string().nullable().optional(),
-  method: zod.z.string().nullable().optional(),
-  sensitive_data_involved: zod.z.boolean().optional().default(false),
-  contains_phi: zod.z.boolean().optional().default(false),
-  sensitive_domain: zod.z.boolean().optional().default(false)
+  tool_name: nonEmptyString().describe("Tool identifier."),
+  tool_category: zod.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: zod.z.boolean().nullable().describe(
+    "Whether policy allowed the tool call; null means authorization is unknown."
+  ),
+  safety_critical: zod.z.boolean().describe("Whether the call can create serious consequences."),
+  external_side_effect: zod.z.boolean().describe(
+    "Whether the action changes state outside the model context."
+  ),
+  tool_call_success: zod.z.boolean().nullable().optional().describe("Whether the tool call succeeded when known."),
+  latency_ms: zod.z.number().nonnegative().nullable().optional().describe("Tool latency in milliseconds when available."),
+  error_code: zod.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: zod.z.number().int().nonnegative().nullable().optional().describe("Size of returned data in bytes when available."),
+  records_accessed: zod.z.number().int().nonnegative().optional().default(0).describe("Number of records touched by the call when available."),
+  contains_sensitive_data: zod.z.boolean().optional().default(false).describe("Whether sensitive data was returned or touched."),
+  action_category: zod.z.string().nullable().optional().describe(
+    "Risk category for the attempted action (e.g. SECURITY, CODE, FINANCIAL, ADMIN) when available."
+  ),
+  method: zod.z.string().nullable().optional().describe("HTTP or RPC method for the tool call when applicable."),
+  sensitive_data_involved: zod.z.boolean().optional().default(false).describe(
+    "Whether sensitive data was involved in the request or result."
+  ),
+  contains_phi: zod.z.boolean().optional().default(false).describe(
+    "Whether protected health information was returned or touched."
+  ),
+  sensitive_domain: zod.z.boolean().optional().default(false).describe("Whether the tool call applies to a sensitive domain.")
 });
 BaseEventSchema.extend({
   signal_payload: ToolCallSignalPayloadSchema
@@ -1229,27 +1323,29 @@ var createToolCallEvent = (event) => {
   return buildRawEventRequest(event, signalPayload, "TOOL_CALL");
 };
 var TransactionSignalPayloadSchema = zod.z.object({
-  amount: zod.z.number().nonnegative().default(0),
-  amount_minor: zod.z.number().int().nonnegative().nullable().optional(),
-  amount_usd: zod.z.number().nonnegative().nullable().optional(),
-  currency: zod.z.string().nullable().optional(),
+  amount: zod.z.number().nonnegative().default(0).describe("Transaction amount in base currency"),
+  amount_minor: zod.z.number().int().nonnegative().nullable().optional().describe("Transaction amount in minor units (e.g. cents)"),
+  amount_usd: zod.z.number().nonnegative().nullable().optional().describe("Transaction amount normalized to USD"),
+  currency: zod.z.string().nullable().optional().describe("ISO 4217 currency code"),
   merchant_category: zod.z.string().nullable().optional(),
   merchant_id: zod.z.string().nullable().optional(),
-  channel: zod.z.string().nullable().optional(),
-  country: zod.z.string().nullable().optional(),
-  velocity: zod.z.number().nonnegative().nullable().optional(),
-  external_anomaly_score: zod.z.number().nullable().optional(),
-  geo_distance: zod.z.number().nonnegative().nullable().optional(),
-  geo_distance_km: zod.z.number().nonnegative().nullable().optional(),
-  records_accessed: zod.z.number().int().nonnegative().nullable().optional(),
-  baseline_records_accessed: zod.z.number().int().nonnegative().nullable().optional(),
-  sensitivity_level: zod.z.string().nullable().optional(),
-  export_count: zod.z.number().int().nonnegative().nullable().optional(),
-  bulk_export: zod.z.boolean().optional().default(false),
-  contains_phi: zod.z.boolean().optional().default(false),
-  control_command: zod.z.string().nullable().optional(),
-  authorized: zod.z.boolean().nullable().optional(),
-  safety_critical: zod.z.boolean().optional().default(false)
+  channel: zod.z.string().nullable().optional().describe("Transaction channel (WEB, MOBILE, ECOM)"),
+  country: zod.z.string().nullable().optional().describe("ISO 3166-1 alpha-2 country code"),
+  velocity: zod.z.number().nonnegative().nullable().optional().describe("Transactions per minute"),
+  external_anomaly_score: zod.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: zod.z.number().nonnegative().nullable().optional().describe("Distance in km from usual location"),
+  geo_distance_km: zod.z.number().nonnegative().nullable().optional().describe("Distance in km from usual location"),
+  records_accessed: zod.z.number().int().nonnegative().nullable().optional().describe("Count of records touched in this transaction"),
+  baseline_records_accessed: zod.z.number().int().nonnegative().nullable().optional().describe("Typical or policy baseline record count for comparison"),
+  sensitivity_level: zod.z.string().nullable().optional().describe("Data sensitivity (e.g. LOW, MEDIUM, HIGH)"),
+  export_count: zod.z.number().int().nonnegative().nullable().optional().describe("Number of export operations"),
+  bulk_export: zod.z.boolean().optional().default(false).describe("Whether this is a bulk export"),
+  contains_phi: zod.z.boolean().optional().default(false).describe("Whether exported or accessed data includes PHI"),
+  control_command: zod.z.string().nullable().optional().describe("Issued control or OT command (e.g. VALVE_OPEN)"),
+  authorized: zod.z.boolean().nullable().optional().describe("Whether the action was authorized; omit if unknown"),
+  safety_critical: zod.z.boolean().optional().default(false).describe("Whether the transaction affects safety-critical systems")
 });
 BaseEventSchema.extend({
   signal_payload: TransactionSignalPayloadSchema
@@ -1282,13 +1378,19 @@ var FEEDBACK_ISSUE_TYPES = [
 
 // src/v1/schemas/user-feedback.ts
 var UserFeedbackSignalPayloadSchema = zod.z.object({
-  feedback_type: zod.z.enum(FEEDBACK_TYPES),
-  rating: zod.z.number().nullable().optional(),
-  reported_issue: zod.z.boolean().optional().default(false),
-  issue_type: zod.z.enum(FEEDBACK_ISSUE_TYPES).nullable().optional(),
-  severity: fraction01Nullable(),
-  response_id: zod.z.string().nullable().optional(),
-  user_comment_hash: zod.z.string().nullable().optional()
+  feedback_type: zod.z.enum(FEEDBACK_TYPES).describe(
+    "User feedback category: THUMBS_UP, THUMBS_DOWN, REPORT, CORRECTION, or RATING."
+  ),
+  rating: zod.z.number().nullable().optional().describe("Optional rating in [-1, 1] or on a 1\u20135 scale."),
+  reported_issue: zod.z.boolean().optional().default(false).describe("Whether the user reported a problem."),
+  issue_type: zod.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: zod.z.string().nullable().optional().describe("Identifier of the response being evaluated."),
+  user_comment_hash: zod.z.string().nullable().optional().describe("Hash of optional user comment when available.")
 });
 BaseEventSchema.extend({
   signal_payload: UserFeedbackSignalPayloadSchema
@@ -1323,22 +1425,28 @@ var WORKFLOW_ACTOR_TYPES = ["USER", "AI_AGENT", "SYSTEM"];
 
 // src/v1/schemas/workflow-action.ts
 var WorkflowActionSignalPayloadSchema = zod.z.object({
-  workflow_id: nonEmptyString(),
-  workflow_type: nonEmptyString(),
-  action_name: nonEmptyString(),
-  action_category: zod.z.enum(WORKFLOW_ACTION_CATEGORIES),
-  action_stage: zod.z.enum(WORKFLOW_ACTION_STAGES),
-  actor_type: zod.z.enum(WORKFLOW_ACTOR_TYPES),
-  requires_approval: zod.z.boolean().optional().default(false),
-  approval_present: zod.z.boolean().optional().default(false),
-  external_side_effect: zod.z.boolean().nullable().optional(),
-  safety_critical: zod.z.boolean().nullable().optional(),
-  amount_usd: zod.z.number().nonnegative().nullable().optional(),
-  sensitive_data_involved: zod.z.boolean().optional().default(false),
-  new_counterparty: zod.z.boolean().optional().default(false),
-  is_new_vendor: zod.z.boolean().optional().default(false),
-  is_new_recipient: zod.z.boolean().optional().default(false),
-  is_new_endpoint: zod.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: zod.z.enum(WORKFLOW_ACTION_CATEGORIES).describe(
+    "Risk category: FINANCIAL, DATA_ACCESS, COMMUNICATION, ADMIN, SECURITY, CODE, or OTHER."
+  ),
+  action_stage: zod.z.enum(WORKFLOW_ACTION_STAGES).describe(
+    "Lifecycle stage: PROPOSED, PRE_EXECUTION, EXECUTED, FAILED, or ROLLED_BACK."
+  ),
+  actor_type: zod.z.enum(WORKFLOW_ACTOR_TYPES).describe("Who initiated the action: USER, AI_AGENT, or SYSTEM."),
+  requires_approval: zod.z.boolean().optional().default(false).describe("Whether approval is required before execution."),
+  approval_present: zod.z.boolean().optional().default(false).describe("Whether required approval is present."),
+  external_side_effect: zod.z.boolean().nullable().optional().describe("Whether the action changes external state when known."),
+  safety_critical: zod.z.boolean().nullable().optional().describe(
+    "Whether the action is safety, security, or business critical when known."
+  ),
+  amount_usd: zod.z.number().nonnegative().nullable().optional().describe("Financial magnitude in USD when applicable."),
+  sensitive_data_involved: zod.z.boolean().optional().default(false).describe("Whether sensitive data was touched."),
+  new_counterparty: zod.z.boolean().optional().default(false).describe("Whether a new vendor, customer, or recipient is involved."),
+  is_new_vendor: zod.z.boolean().optional().default(false).describe("Whether the action involves a new vendor."),
+  is_new_recipient: zod.z.boolean().optional().default(false).describe("Whether the action involves a new recipient."),
+  is_new_endpoint: zod.z.boolean().optional().default(false).describe("Whether the action targets a new endpoint.")
 });
 BaseEventSchema.extend({
   signal_payload: WorkflowActionSignalPayloadSchema