kind: uapf.algorithm.card
id: algo.incident_triage.normalize_signal
version: 1.0.0
name: Signal normalizer
intent: |
  Reads a freshly-received Signal row by id and folds the
  source-specific payload (Zabbix event, IMAP email, Jira DC issue,
  manual entry) into a single normalised shape with the fields
  downstream cards expect: title, description, host, severity, source
  hint, optional contact metadata, and a content-hash for dedupe.
  Idempotent; safe to re-run.
algorithm_kind: transformer

io:
  inputs:
    - id: signal_id
      type: string
      cardinality: single
      constraints:
        pattern: "^[0-9a-fA-F-]{36}$"
      documentation: UUID of the Signal row to normalise.
  outputs:
    - id: normalized_payload
      type: object
      documentation: |
        Adapter-agnostic dictionary. Stable keys: title, description,
        host, severity (one of disaster|high|critical|average|warning|low|info),
        source, source_event_id, optional received_at, optional contact_email.
    - id: dedupe_hash
      type: string
      documentation: SHA-256 hex over (source, source_event_id, host) used to suppress repeat signals.
    - id: source_kind
      type: string
      documentation: One of zabbix|email|jira_dc|jira_cloud|manual|cti.

implementation:
  type: external
  medium: mcp_tool
  uri: uapf-ip://capability/intake.normalize@1
  hash: sha256:0000000000000000000000000000000000000000000000000000000000000000
  runtime:
    capability: intake.normalize@1
    note: |
      Host-fulfilled UAPF-IP capability. The OpenITSM host's
      intake.normalize handler implements one normaliser per source.
      Hash is a placeholder until the runtime publishes the
      implementation hash.

determinism: deterministic
side_effects: pure
complexity:
  typical_latency_ms: 30
  max_latency_ms: 2000
failure_mode: |
  Returns source_kind='unknown' with whatever raw_payload was available
  on the signal row. Triage continues with best-effort classification.

owners:
  - type: team
    id: openitsm-stewards
    contact: stewards@openitsm.algomation.io

lifecycle:
  status: draft

tests:
  - name: zabbix-link-down
    description: |
      Zabbix event for a transport-link outage on an edge router.
      Title, host and severity are normalised from the raw event shape.
    inputs:
      signal_id: "11111111-1111-1111-1111-111111111111"
    expected_outputs:
      source_kind: "zabbix"
      normalized_payload:
        title: "Link down on edge router rtr-r1"
        host: "rtr-r1.lvrtc.lv"
        severity: "high"
        source: "zabbix"
  - name: email-customer-lv
    description: |
      Customer-facing Latvian-language email about a bandwidth uplift
      request. Subject becomes title; body becomes description.
    inputs:
      signal_id: "22222222-2222-2222-2222-222222222222"
    expected_outputs:
      source_kind: "email"
      normalized_payload:
        title: "Klients SIA Latvija Tev: lūgums palielināt joslas platumu"
        severity: "average"
        source: "email"