WDP Part 4: Sequence Field Specification

Abstract#

This document specifies the Sequence Field (Part 4) of the Waddling Diagnostic Protocol (WDP) error code structure. The sequence field uniquely identifies a specific diagnostic code within the Component.Primary namespace, providing the most granular level of classification.

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 Overview

The sequence field is the fourth part of the five-part WDP error code structure:

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 4: Unique identifier within category (THIS DOCUMENT)

The sequence field provides the final level of specificity, uniquely identifying a particular diagnostic event within the Component.Primary namespace.

1.2 Purpose

The sequence field serves to:

1. Uniquely identify specific diagnostic codes within a category
2. Enable evolution by allowing new error codes to be added over time without breaking existing ones
3. Provide ordering for related diagnostics
4. Support conventions for common error patterns (see 6-SEQUENCE-CONVENTIONS.md)
5. Form canonical identity for hash computation

1.3 Example

Component.Primary = Auth.Token

Sequences within Auth.Token:
  001 - Token missing
  002 - Token malformed
  003 - Token invalid signature
  004 - Token expired
  005 - Token not yet valid
  ...

Catalog Evolution Example:

Version 1.0:  E.Auth.Token.001, E.Auth.Token.003, E.Auth.Token.018
Version 1.1:  Add E.Auth.Token.031 (new error type)
Version 1.2:  Add E.Auth.Token.032 (another new error type)

→ Existing codes (001-003) remain unchanged
→ New codes added incrementally
→ No breaking changes to existing systems

1.4 Design Goals

The sequence field design adheres to the following principles:

• Numeric canonical form: Three-digit zero-padded numbers provide stable identity for hash computation
• Alias support: Named sequences provide semantic meaning without affecting canonical identity
• Range sufficiency: 999 sequences per Component.Primary accommodates most use cases
• Convention compatibility: Works with semantic conventions defined in 6-SEQUENCE-CONVENTIONS.md
• Internationalization: Numeric identity is language-independent

2. Format Options#

WDP supports two sequence format options:

2.1 Numeric Format (RECOMMENDED)

Pattern: Exactly three digits (zero-padded)

Regex: [0-9]{3}

Range: 001 to 999

Examples:

001
002
003
...
999

2.2 Named Format (OPTIONAL)

Pattern: SCREAMING_SNAKE_CASE

Regex: [A-Z][A-Z0-9_]*

Examples:

MISSING
INVALID
EXPIRED
NOT_FOUND
REVOKED

Important: Named sequences are display aliases only. They MUST be resolved to their numeric canonical form before hash computation.

3. Field Specification#

3.1 Field Properties

3.2 Character Sets

Numeric sequences:

• ASCII digits only: 0-9
• Exactly 3 characters
• Zero-padded (e.g., 001, not 1)

Named sequences:

• ASCII uppercase letters: A-Z
• ASCII digits: 0-9
• Underscore: _
• Must start with uppercase letter
• No maximum length (RECOMMENDED: 8-24 characters)

4. Numeric Sequences (Canonical)#

4.1 Overview

Numeric sequences are the canonical identity for WDP error codes.

Range: 001 to 999 (999 possible sequences per Component.Primary)

Format: Exactly three digits, zero-padded

Examples:

001, 002, 003, ..., 098, 099, 100, ..., 999

Important: The zero-padding is REQUIRED and is part of the canonical identity used for hash computation.

4.2 Benefits

Numeric sequences provide the following advantages:

• Simple allocation - Easy to increment and assign
• Clear ordering - Natural sequence for related errors
• Stable identity - Associated names can change without affecting the hash
• Compact display - Short and readable
• Convention support - Works well with semantic conventions (001=MISSING, etc.)
• Internationalization - Language-independent canonical form

4.3 Range Sufficiency

The range of 999 sequences per Component.Primary is sufficient for most use cases:

If more than 999 errors are needed in a single Component.Primary:

This condition often indicates a design issue. Implementations SHOULD consider splitting into more specific subcategories:

Instead of:
E.Parser.*.001-999  (too many in one Primary)

Consider:
E.Parser.Syntax.001-150
E.Parser.Semantic.001-100
E.Parser.Lexical.001-50
E.Parser.Type.001-80

4.4 Format Rules

Implementations MUST:

• Use exactly three digits
• Zero-pad values less than 100 (e.g., 001, not 1)
• Stay within range 001-999

Implementations MUST NOT:

• Use 000 (reserved/invalid)
• Exceed 999
• Omit leading zeros

Hash Input: When computing the compact ID hash, the numeric sequence MUST be zero-padded:

Correct:   E.AUTH.TOKEN.001  // hash input with zero-padding
Incorrect: E.AUTH.TOKEN.1    // missing padding, produces different hash

5. Named Sequences (Display Aliases)#

5.1 Overview

Named sequences are OPTIONAL display aliases for numeric sequences. They provide semantic meaning in code and documentation but are NOT used for hash computation.

Key Principle: Named sequences MUST resolve to numeric sequences before hashing.

5.2 Format Rules

Pattern: SCREAMING_SNAKE_CASE

Regex: [A-Z][A-Z0-9_]*

Rules:

• MUST start with uppercase letter (A-Z)
• MAY contain uppercase letters, digits, and underscores
• MUST NOT contain lowercase letters, hyphens, or other special characters
• RECOMMENDED length: 8-24 characters

Valid examples:

MISSING
INVALID
EXPIRED
NOT_FOUND
REVOKED
ALREADY_EXISTS
PERMISSION_DENIED

Invalid examples:

missing          // must be uppercase
Missing          // must be SCREAMING_SNAKE_CASE
not-found        // hyphens not allowed
NOT FOUND        // spaces not allowed
_MISSING         // must start with letter

5.3 Relationship to Numeric

Example:

Canonical:       E.Auth.Token.001
Associated Name: MISSING
Display Forms:   E.Auth.Token.001
                 E.Auth.Token.MISSING
                 E.Auth.Token.001 (MISSING)
Hash Input:      E.AUTH.TOKEN.001  (always numeric)
Hash Output:     Xy8Qz

5.4 Benefits

Named sequences provide the following advantages:

• Self-documenting - Semantic meaning visible in code
• Memorable - Easier to remember than numbers
• Readable - Clear intent in logs and error messages
• Code constants - Natural fit for programming language constants

5.5 Rationale for Resolution

Named sequences MUST be resolved to numeric form before hashing for the following reasons:

1. Stable Identity: Renaming aliases does not change the hash
2. Internationalization: Names can be localized while numeric identity remains universal
3. Simplicity: Hash input contains only alphanumeric characters and periods (no underscores)
4. Flexibility: Names are OPTIONAL and implementation-defined
5. Deterministic: The same numeric sequence always produces the same hash

6. Hash Canonical Form#

6.1 Hash Input Normalization

Before computing the compact ID hash, the sequence field MUST be:

1. Resolved to numeric form (if a named alias is used)
2. Included as part of the uppercase-normalized full code

6.2 Normalization Flow

Numeric sequence (no resolution needed):

Display:     E.Auth.Token.001
             ↓ normalize to uppercase
Hash Input:  E.AUTH.TOKEN.001  (note: 001 with zero-padding)
             ↓ hash (xxHash64 → Base62)
Compact ID:  Xy8Qz

Key Point: The numeric sequence in the hash input MUST be zero-padded to 3 digits:

• Sequence 1 → Hash input uses 001
• Sequence 42 → Hash input uses 042
• Sequence 123 → Hash input uses 123

Named sequence (resolve first):

Display:     E.Auth.Token.MISSING
             ↓ resolve named → numeric
Resolved:    E.Auth.Token.001
             ↓ normalize to uppercase
Hash Input:  E.AUTH.TOKEN.001
             ↓ hash (xxHash64 → Base62)
Compact ID:  Xy8Qz  (same as numeric!)

6.3 Key Properties

Same numeric sequence produces the same hash:

E.Auth.Token.001              → Xy8Qz
E.Auth.Token.MISSING          → Xy8Qz  (resolves to 001)

Both produce the same hash because they resolve to:
E.AUTH.TOKEN.001  (with zero-padded 001)

Zero-padding matters for hash computation:

✅ E.AUTH.TOKEN.001 → Xy8Qz  (correct format)
❌ E.AUTH.TOKEN.1   → ???    (invalid - different hash, don't use!)

Different numeric sequences → Different hashes:

E.Auth.Token.001  → Xy8Qz
E.Auth.Token.003  → Ab3Cd
E.Auth.Token.018  → Mn7Pq

7. Choosing Between Formats#

7.1 Decision Matrix

7.2 Hybrid Approach (RECOMMENDED)

Implementations SHOULD use numeric sequences as canonical identity and associate semantic names for documentation and code constants.

Pattern:

// Define named constants in a module namespace
mod auth_token {
    pub const MISSING: u32 = 001;
    pub const EXPIRED: u32 = 018;
    pub const INVALID: u32 = 003;
}

// Use in code
fn create_error() -> String {
    format!("E.Auth.Token.{:03}", auth_token::MISSING)
    // Result: "E.Auth.Token.001"
}

Catalog documents both:

{
  "E.Auth.Token.001": {
    "name": "MISSING",
    "compact_id": "Xy8Qz",
    "message": "Token missing from Authorization header"
  },
  "E.Auth.Token.018": {
    "name": "EXPIRED",
    "compact_id": "Ab3Cd",
    "message": "Token has expired"
  }
}

7.3 Comparison of Approaches

Pure Numeric:

E.Auth.Token.001
E.Auth.Token.018
E.Auth.Token.003

• Simple
• Direct hash computation
• Requires external documentation

Pure Named:

E.Auth.Token.MISSING
E.Auth.Token.EXPIRED
E.Auth.Token.INVALID

• Self-documenting
• Requires resolution mechanism
• More complex implementation

Hybrid (RECOMMENDED):

Code:    const MISSING = 001;  // in auth_token module
Display: E.Auth.Token.001
Alias:   MISSING
Catalog: Maps 001 ↔ MISSING
Hash:    Always from 001

• Combines advantages of both approaches
• Flexible display options
• Stable identity

7.4 Non-Conventional Usage (NOT RECOMMENDED)

While the WDP sequence format is normative, sequence semantic conventions are informative. Projects MAY choose not to follow the conventions defined in 6-SEQUENCE-CONVENTIONS.md, though this is NOT RECOMMENDED.

Example of non-conventional usage (discouraged):

// Sequential numbering without semantic meaning
E.Auth.Token.001              - Token missing
E.Auth.Token.002              - Token malformed  
E.Auth.Token.003              - Token invalid signature
E.Auth.Token.004              - Token expired
E.Auth.Token.005              - Token not yet valid

Recommended conventional alternative:

// Semantic numbering following conventions
E.Auth.Token.001              - Token missing (001 = MISSING)
E.Auth.Token.002              - Token type mismatch (002 = MISMATCH)  
E.Auth.Token.003              - Token invalid signature (003 = INVALID)
E.Auth.Token.018              - Token expired (018 = STALE)
E.Auth.Token.018              - Token not yet valid (018 = STALE)

Rationale for following conventions:

• Consistency across projects and organizations
• Predictable error patterns for developers
• Easier debugging and error recognition
• Interoperability between systems

See 6-SEQUENCE-CONVENTIONS.md for complete semantic guidance.

8. Implementation Patterns#

8.1 Pattern A: Code Constants (RECOMMENDED)

// Named constants in a module namespace
mod auth_token {
    pub const MISSING: u32 = 001;
    pub const EXPIRED: u32 = 018;
    pub const INVALID: u32 = 003;
}

pub fn format_error_code(seq: u32) -> String {
    format!("E.Auth.Token.{:03}", seq)
}

// Usage
let code = format_error_code(auth_token::MISSING);
// Result: "E.Auth.Token.001"

8.2 Pattern B: Catalog Mapping

{
  "sequences": {
    "001": {
      "name": "MISSING",
      "message": "Token missing from Authorization header"
    },
    "018": {
      "name": "EXPIRED",
      "message": "Token has expired"
    }
  }
}

8.3 Pattern C: Enum with Numeric Values

#[repr(u32)]
pub enum TokenError {
    Missing = 001,
    Expired = 018,
    Invalid = 003,
}

impl TokenError {
    pub fn to_code(&self) -> String {
        format!("E.Auth.Token.{:03}", *self as u32)
    }
}

// Usage
let code = TokenError::Missing.to_code();
// Result: "E.Auth.Token.001"

8.4 Pattern D: Resolution Function

pub fn resolve_sequence(seq: &str) -> String {
    match seq {
        "MISSING" => "001".to_string(),
        "EXPIRED" => "018".to_string(),
        "INVALID" => "003".to_string(),
        // If already numeric, pass through
        s if s.chars().all(|c| c.is_ascii_digit()) => s.to_string(),
        _ => panic!("Unknown sequence: {}", seq),
    }
}

// Usage
let numeric = resolve_sequence("MISSING");
// Result: "001"

9. Validation Rules#

9.1 Numeric Sequence Validation

Implementations MUST validate that numeric sequences:

1. Contain exactly 3 ASCII digits
2. Are within range 001-999 (000 is invalid)
3. Are zero-padded (e.g., 001, not 1)

Regex:

^(0[0-9]{2}|[1-9][0-9]{2})$

Explanation:

• 0[0-9]{2} - 001-099
• [1-9][0-9]{2} - 100-999

Simplified (if range checking separately):

^[0-9]{3}$

Then check: 001 ≤ value ≤ 999

9.2 Named Sequence Validation

Implementations MUST validate that named sequences:

1. Start with uppercase ASCII letter
2. Contain only uppercase letters, digits, and underscores
3. Do not start with underscore or digit

Regex:

^[A-Z][A-Z0-9_]*$

9.3 Validation Examples

Valid Numeric:

001
042
100
999

Invalid Numeric:

000  // reserved/invalid
1    // must be 3 digits (should be 001)
01   // must be 3 digits (should be 001)
1000 // exceeds 999
ABC  // not numeric

Valid Named:

MISSING
EXPIRED
NOT_FOUND
ALREADY_EXISTS
HTTP_404

Invalid Named:

missing           // must be uppercase
Expired           // must be all uppercase
not-found         // hyphens not allowed
_MISSING          // cannot start with underscore
404_HTTP          // cannot start with digit

10. Examples#

10.1 Numeric Sequences

Authentication errors:

E.Auth.Token.001            - Token missing (001 = MISSING)
E.Auth.Token.002            - Token type mismatch (002 = MISMATCH)
E.Auth.Token.003            - Token invalid signature (003 = INVALID)
E.Auth.Token.018            - Token expired (018 = STALE)
E.Auth.Token.031            - Custom token validation error

Database errors:

E.Database.Connection.001   - Connection string missing
E.Database.Connection.017   - Connection timeout
E.Database.Connection.021   - Database not found
E.Database.Connection.027   - Database unavailable

10.2 Named Sequences (Aliases)

Authentication errors:

E.Auth.Token.MISSING        - Alias for 001
E.Auth.Token.MALFORMED      - Alias for 002
E.Auth.Token.INVALID        - Alias for 003
E.Auth.Token.EXPIRED        - Alias for 004
E.Auth.Token.NOT_YET_VALID  - Alias for 005

Database errors:

E.Database.Connection.MISSING       - Alias for 001
E.Database.Connection.TIMEOUT       - Alias for 017
E.Database.Connection.NOT_FOUND     - Alias for 021
E.Database.Connection.UNAVAILABLE   - Alias for 027

10.3 Hash Equivalence

All of these produce the same compact ID:

E.Auth.Token.001            → Hash input: E.AUTH.TOKEN.001 → Xy8Qz
E.Auth.Token.MISSING        → Resolves to 001 → E.AUTH.TOKEN.001 → Xy8Qz
E.Auth.Token.018            → Hash input: E.AUTH.TOKEN.018 → Ab3Cd
E.Auth.Token.EXPIRED        → Resolves to 018 → E.AUTH.TOKEN.018 → Ab3Cd

10.4 Mixed Display Forms

Within the same project:

E.Auth.Token.001            - Numeric (canonical)
E.Parser.Syntax.UNEXPECTED  - Named (alias, resolves to numeric)
E.Database.Query.031        - Numeric (canonical, project-specific)
E.Network.Timeout.017       - Numeric (017 = TIMEOUT, conventional)

All named forms resolve to numeric before hashing.

10.5 Complete Examples with Catalogs

Error Code:

E.Auth.Token.001
E.Auth.Token.018
E.Auth.Token.003

Catalog Entry:

{
  "E.Auth.Token.001": {
    "sequence_name": "MISSING",
    "compact_id": "Xy8Qz",
    "message": "Authentication token missing from request",
    "severity": "E",
    "component": "Auth",
    "primary": "Token",
    "sequence": "001",
    "tone": "negative",
    "priority": 8,
    "blocking": true
  },
  "E.Auth.Token.018": {
    "sequence_name": "EXPIRED",
    "compact_id": "Ab3Cd",
    "message": "Authentication token has expired",
    "severity": "E",
    "component": "Auth",
    "primary": "Token",
    "sequence": "018",
    "tone": "negative",
    "priority": 8,
    "blocking": true
  }
}

Normative References#

• STRUCTURE.md - WDP error code structure overview
• 1-SEVERITY.md - Severity field specification
• 2-COMPONENT.md - Component field specification
• 3-PRIMARY.md - Primary field specification
• 5-COMPACT-IDS.md - Compact ID generation
• 7-SEQUENCE-CONVENTIONS.md - Sequence conventions (informative)

Informative References#

• RFC 2119 - Key words for RFCs

Conformance#

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.