WDP Part 1: Severity Field Specification

Abstract#

This document specifies Part 1 of the Waddling Diagnostic Protocol (WDP): the Severity field. The severity field is a single-character indicator that communicates the urgency, impact, and classification of a diagnostic code. WDP defines nine severity levels, each with distinct semantics, priority values, and blocking characteristics.

Specification Navigation: See STRUCTURE.md for an overview of all WDP specification parts.

Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1. Introduction#

1.1 Purpose

The severity field is the first part of a WDP diagnostic code. It provides an immediate indication of:

• Urgency: The priority level requiring attention
• Impact: The consequence of the diagnostic condition
• Classification: Whether the condition represents an error, warning, success, or informational message
• Blocking: Whether the condition prevents further execution

1.2 Position in Error Code

Complete WDP Structure:

Severity.Component.Primary.Sequence -> CompactID
    ^         ^        ^        ^          ^
  Part 1    Part 2   Part 3   Part 4    Part 5

This Document Focus:

Severity.Component.Primary.Sequence -> CompactID
^^^^^^^^
Part 1: Single character indicating urgency (THIS DOCUMENT)

Example: E.Auth.Token.001 - The E indicates an Error severity.

1.3 Design Goals

The severity field design adheres to the following principles:

• Single character: Compact representation for efficient parsing and display
• Mnemonic codes: Letters that suggest meaning (E=Error, W=Warning, etc.)
• Comprehensive coverage: All diagnostic needs including errors, warnings, successes, and traces
• Prioritizable: Deterministic ordering by urgency level
• Universal semantics: Consistent interpretation across all languages and platforms

2. Severity Levels#

WDP defines nine severity levels. Each severity level MUST be represented by exactly one uppercase ASCII letter from the set [EWCBSHKIT].

2.1 Complete Severity Table

2.2 Severity Definitions

E - Error (Priority 8)

Blocking: Yes
Tone: Negative

Definition: An Error severity indicates that an operation has failed and cannot continue. Implementations MUST use this severity for conditions that prevent normal execution, including invalid inputs, logic errors, and unrecoverable failures.

Applicable conditions:

• Required parameter is missing
• Invalid data format or type
• Business logic violation
• Resource access denied
• Operation failed unexpectedly

Examples:

E.Auth.Token.001         - Missing authentication token
E.Parser.Syntax.003      - Invalid syntax in input
E.Database.Query.FAILED  - Database query failed
E.FileSystem.File.021    - File not found

B - Blocked (Priority 7)

Blocking: Yes
Tone: Negative

Definition: A Blocked severity indicates that an operation cannot proceed due to an external constraint. Implementations SHOULD use this severity for conditions involving resource contention, deadlocks, or I/O operation timeouts.

Applicable conditions:

• Waiting for mutex/lock acquisition
• I/O operation blocked or timed out
• Deadlock detected
• Network connection unavailable
• Resource temporarily unavailable

Examples:

B.Thread.Mutex.024       - Waiting for mutex lock
B.Io.Wait.TIMEOUT        - I/O operation blocked/timeout
B.Network.Connection.027 - Network connection unavailable
B.Database.Lock.024      - Database row locked by another transaction

Distinction from Error: Blocked conditions are typically temporary and MAY resolve without intervention (e.g., lock released, network restored). Errors typically require user or developer action to resolve.

C - Critical (Priority 6)

Blocking: No
Tone: Negative

Definition: A Critical severity indicates a severe problem that requires immediate attention but does not necessarily block execution. Implementations SHOULD use this severity for conditions such as data corruption, resource exhaustion, or system instability.

Applicable conditions:

• Data corruption detected
• Resource nearly exhausted (disk, memory)
• System stability threatened
• Security breach detected
• Irreversible failure occurred

Examples:

C.Data.Integrity.025     - Data corruption detected
C.Memory.Exhausted.026   - Out of memory
C.Disk.Full.026          - Disk space exhausted
C.Security.Breach.008    - Security violation detected

Distinction from Error: Critical conditions MAY allow continued execution (possibly in degraded mode) but indicate serious problems requiring immediate operator attention.

W - Warning (Priority 5)

Blocking: No
Tone: Negative

Definition: A Warning severity indicates a potentially problematic situation that does not prevent operation but MAY lead to errors or unexpected behavior. Implementations SHOULD use this severity for deprecated features, configuration issues, or edge cases.

Applicable conditions:

• Deprecated API or feature used
• Sub-optimal configuration
• Edge case encountered
• Performance degradation
• Recoverable error occurred

Examples:

W.Api.Deprecated.010     - API method deprecated
W.Cache.Miss.018         - Cache miss (degraded performance)
W.Config.Default.USED    - Using default configuration
W.Parser.Ambiguous.003   - Ambiguous syntax (guessing interpretation)

H - Help (Priority 4)

Blocking: No
Tone: Neutral

Definition: A Help severity provides suggestions, tips, or guidance to users or developers. This severity is NOT an error or warning; it represents advisory information that MAY improve the user experience or system performance.

Applicable conditions:

• Usage suggestions
• Performance optimization tips
• Configuration recommendations
• Best practice guidance
• Tutorial or learning content

Examples:

H.Usage.Tip.SUGGESTION   - Helpful usage suggestion
H.Perf.Optimization.001  - Performance optimization tip
H.Config.Recommended.001 - Recommended configuration
H.Security.BestPractice  - Security best practice

S - Success (Priority 3)

Blocking: No
Tone: Positive

Definition: A Success severity indicates that an operation completed successfully. Implementations MAY use this severity to provide explicit positive feedback, particularly for operations where absence of output might be ambiguous.

Applicable conditions:

• Authentication/login succeeded
• File uploaded successfully
• Transaction committed
• Validation passed
• Operation explicitly succeeded

Examples:

S.Auth.Login.SUCCESS     - Login successful
S.Upload.Complete.999    - File upload finished successfully
S.Transaction.Commit.999 - Transaction committed
S.Validation.Pass.999    - Validation passed

K - Completed (Priority 2)

Blocking: No
Tone: Positive

Definition: A Completed severity indicates that a long-running task or phase has finished. The letter "K" is used to avoid conflict with "C" (Critical) and "S" (Success). Implementations MAY use this severity to signal completion of multi-step operations.

Applicable conditions:

• Build completed
• Migration finished
• Backup completed
• Batch processing finished
• Long-running task done

Examples:

K.Build.Done.999         - Build completed
K.Migration.Finished.999 - Database migration finished
K.Backup.Complete.999    - Backup completed
K.BatchJob.Done.999      - Batch processing completed

Distinction from Success: Success SHOULD be used for individual operations; Completed SHOULD be used for multi-step tasks or phases.

I - Info (Priority 1)

Blocking: No
Tone: Neutral

Definition: An Info severity provides status updates, milestones, or general information about system state or operations. Implementations MAY use this severity for routine operational messages.

Applicable conditions:

• Server starting/stopping
• Request received
• Configuration loaded
• Status updates
• Statistics or metrics

Examples:

I.Server.Startup.001     - Server starting up
I.Request.Received.001   - HTTP request received
I.Cache.Stats.001        - Cache statistics
I.Config.Loaded.001      - Configuration loaded

T - Trace (Priority 0)

Blocking: No
Tone: Neutral

Definition: A Trace severity is used for detailed execution traces, debugging information, profiling, and performance measurements. Implementations SHOULD enable this severity only during development or debugging due to potential performance impact.

Applicable conditions:

• Function entry/exit (profiling)
• Timer checkpoints
• Execution probes
• Variable state dumps
• Performance measurements

Examples:

T.Function.Entry.001     - Function entered (profiling)
T.Timer.Start.001        - Timer started
T.Probe.Checkpoint.001   - Execution checkpoint
T.Variable.Dump.001      - Variable state dump

3. Field Specification#

3.1 Format

The severity field MUST conform to the following specification:

3.2 Validation Rules

Implementations MUST accept only the following severity characters:

E, W, C, B, S, K, I, T, H

The following regular expression MUST be used for validation:

^[EWCBSHKIT]$

Severity codes MUST be uppercase. Implementations MUST reject lowercase letters as invalid.

Valid examples:

E  // Valid: Error severity
W  // Valid: Warning severity
S  // Valid: Success severity

Invalid examples:

e  // Invalid: lowercase NOT permitted
X  // Invalid: not a defined severity
ER // Invalid: multiple characters NOT permitted

4. Priority System#

4.1 Purpose

Each severity level has an associated priority value in the range 0-8, where higher values indicate greater urgency. Priority values enable:

• Sorting diagnostics by importance
• Filtering by minimum priority threshold
• Alert routing based on urgency
• Log level configuration

4.2 Priority Values

4.3 Priority Ordering

Complete ordering (lowest to highest):

T(0) < I(1) < K(2) < S(3) < H(4) < W(5) < C(6) < B(7) < E(8)

4.4 Use Cases

Filtering by priority:

Show only priority >= 5:  W, C, B, E (warnings and above)
Show only priority >= 7:  B, E (blocking conditions only)
Show only priority >= 1:  All except Trace

Alert routing:

Priority 8 (E): Page on-call engineer
Priority 7 (B): Alert operations team
Priority 6 (C): Email alerts
Priority 5 (W): Log aggregation
Priority 0-4: Standard logging

5. Blocking Semantics#

5.1 Blocking vs Non-Blocking

Blocking severities (E, B):

Diagnostics with blocking severities indicate that the operation cannot proceed. Implementations MUST treat these as terminal conditions that:

• Halt or suspend execution
• Require intervention (user, system, or time)
• Return an error result or raise an exception

Non-blocking severities (C, W, H, S, K, I, T):

Diagnostics with non-blocking severities indicate that the operation MAY continue. These conditions:

• Permit continued execution (possibly degraded)
• Provide information, warnings, or confirmations
• Do not halt execution
• Return success or informational status

5.2 Examples

Blocking:

E.Auth.Token.001         → Cannot proceed without token
B.Thread.Mutex.024       → Waiting for lock release
E.Database.Connection.021 → Cannot query without connection

Non-blocking:

W.Api.Deprecated.010     → Can proceed, but API will be removed
C.Memory.Low.026         → System continues but at risk
S.Auth.Login.SUCCESS     → Operation succeeded, continue

6. Tone Classification#

6.1 Overview

WDP severities are classified by tone, representing the nature or character of the diagnostic message. Tone classification is OPTIONAL but RECOMMENDED for implementations that perform filtering, routing, or analytics based on diagnostic character.

6.2 Negative Tone (E, B, C, W)

Indicates: Problems or concerns
Priority Range: 5-8

Severities with negative tone indicate conditions that require attention:

• E (Error): Operation failed
• B (Blocked): Operation cannot proceed
• C (Critical): Severe condition detected
• W (Warning): Potential problem identified

6.3 Positive Tone (S, K)

Indicates: Successful outcomes
Priority Range: 2-3

Severities with positive tone indicate successful completion:

• S (Success): Operation completed successfully
• K (Completed): Task or phase finished

6.4 Neutral Tone (H, I, T)

Indicates: Informational or advisory content
Priority Range: 0-4

Severities with neutral tone provide information without indicating success or failure:

• H (Help): Advisory information
• I (Info): Status update
• T (Trace): Debug trace

6.5 Use in Analysis

Implementations MAY use tone classification for operational analysis:

Dashboard health scoring:

Negative tone count: High → System health degraded
Positive tone count: High → System health nominal
Neutral tone: Informational only

Alert routing:

Negative tone (E, B, C, W): Trigger alerts
Positive tone (S, K): Optional notifications
Neutral tone (H, I, T): Logging only

7. Use Cases by Severity#

This section provides illustrative examples for each severity level. These examples are INFORMATIVE and demonstrate typical usage patterns.

7.1 Error (E) - Examples

E.Auth.Token.001         - Missing authentication token
E.Auth.Token.003         - Invalid token format
E.Auth.Permission.008    - Permission denied

E.Parser.Syntax.003      - Invalid syntax in input
E.Parser.Token.001       - Unexpected token

E.Database.Query.FAILED  - Database query failed
E.Database.Connection.021 - Database not found

E.FileSystem.File.021    - File not found
E.FileSystem.File.008    - Permission denied

E.Network.Connection.028 - Host unreachable
E.Network.Timeout.017    - Connection timeout