Extended Part6 of 12
Version0.1.0-draft
Last Updated2025-11-30
StatusDraft
TypeINFORMATIVE (Non-Normative)

WDP Part 6: Sequence Conventions

Informative guidance on sequence number conventions for the Waddling Diagnostic Protocol (WDP). These conventions are RECOMMENDED patterns that improve consistency and recognizability across projects, but they are NOT REQUIRED.

Abstract#

This document provides INFORMATIVE (non-normative) guidance on sequence number conventions for the Waddling Diagnostic Protocol (WDP). These conventions are RECOMMENDED patterns that improve consistency and recognizability across projects, but they are NOT REQUIRED. Projects MAY adopt, adapt, or ignore these conventions based on their domain-specific needs.

Key Point: Sequence conventions are suggestions, not rules. Domain semantics always take precedence.

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

WDP sequence numbers (001-999) uniquely identify diagnostic codes within a Component.Primary namespace. While these numbers are technically arbitrary, establishing common conventions provides several benefits:

  • Consistency - Similar errors use similar numbers across projects
  • Recognition - Developers can recognize common patterns instantly
  • Predictability - New team members can guess likely sequence numbers
  • Documentation - Conventions serve as implicit documentation
  • Interoperability - Shared understanding across organizations

1.2 Scope

This document covers:

  • Recommended sequence number patterns for common error types
  • Semantic meanings associated with specific ranges
  • Guidance on when to apply conventions vs deviate
  • Examples demonstrating appropriate and inappropriate usage

This document does NOT cover:

  • Mandatory sequence assignments (all assignments are project-specific)
  • Normative requirements (use 4-SEQUENCE.md for requirements)
  • Complete enumeration of all possible errors

1.3 The Combinatorial Nature

WDP error codes are combinatorial by design:

ANY Severity × ANY Component × ANY Primary × ANY Sequence

This means:

  • The same sequence number can appear in multiple components
  • Each Component.Primary pair defines its own namespace
  • Sequence 001 might mean "missing" in one context and something else in another
  • Conventions suggest common patterns but don't enforce them

2. Status: Informative vs Normative#

2.1 RFC 2119 Interpretation

This document uses RFC 2119 keywords with the following meanings:

2.2 Conformance

Conformance to this document is OPTIONAL. Projects are NOT required to follow these conventions to be WDP-compliant.

WDP compliance requires:

  • Following normative specifications (STRUCTURE.md, 1-SEVERITY.md, etc.)
  • Using valid sequence format (numeric 001-999 or named aliases)
  • Generating correct compact IDs

WDP compliance does NOT require:

  • Following sequence number conventions
  • Using any specific sequence numbers
  • Applying semantic meanings from this document

2.3 When to Deviate

You SHOULD deviate from these conventions when:

  1. Domain semantics differ - Your domain has different natural groupings
  2. Existing systems - Compatibility with legacy error codes is more important
  3. Team preference - Your team has established different conventions
  4. Better organization - You've found a more logical structure for your domain
  5. Semantic mismatch - The convention doesn't make sense in your context

Document your deviations in your project's error catalog to maintain clarity.

3. Convention Overview#

3.1 Three-Tier Structure

The sequence range 001-999 is organized into three tiers:

3.2 Reserved Semantic Ranges (001-030)

The first 30 sequences are organized by error category:

3.3 Rationale

Why these ranges?

  1. Frequency - These patterns occur in most software systems
  2. Recognition - Common enough to be memorable
  3. Flexibility - Broad enough to cover many use cases
  4. Limited scope - Only 30 reserved numbers leaves 969 for custom use

4. Reserved Sequences (001-030)#

4.1 Input/Data Validation (001-010)

These sequences cover errors related to data validation, format checking, and input processing.

Examples:

E.Auth.Token.001         - Token missing from request
E.Database.Config.001    - Database URL missing
E.Parser.Input.001       - Input file not provided

E.FileSystem.Path.003    - Path format invalid
E.Network.Port.003       - Port number invalid

E.Auth.Permission.008    - Permission denied
E.API.Endpoint.009       - Endpoint not supported

4.2 State/Lifecycle (011-020)

These sequences cover errors related to object state, lifecycle management, and temporal conditions.

Examples:

E.Database.Connection.013    - Connection closed
E.Thread.Lock.017            - Lock acquisition timeout
E.Network.Request.017        - Request timeout

E.Cache.Entry.018            - Cache entry stale
E.Auth.Session.018           - Session expired (stale)

E.Process.Startup.011        - Process not initialized
E.Worker.Job.014             - Job cancelled

4.3 Resource/Storage (021-030)

These sequences cover errors related to resource management, storage, and persistence.

Examples:

E.FileSystem.File.021        - File not found
E.Database.Record.021        - Record not found
E.API.Endpoint.021           - Endpoint not found (404)

E.FileSystem.File.022        - File already exists
E.Database.Record.022        - Duplicate key violation

E.Database.Connection.027    - Database unavailable
E.Cache.Server.027           - Cache server unavailable

E.Network.Host.028           - Host unreachable
E.Network.Connection.029     - Connection dropped

5. Project-Specific Sequences (031-897)#

5.1 Overview

Sequences 031-897 (867 total) are available for project-specific error codes without semantic constraints.

Use this range for:

  • Domain-specific errors unique to your system
  • Business logic errors
  • Application-specific validation
  • Custom workflow states
  • Integration-specific errors

5.2 Organization Strategies

Strategy A: Numeric Blocks

031-050  - Authentication subsystem errors
051-080  - Payment processing errors
081-120  - Inventory management errors
121-150  - Shipping/logistics errors

Strategy B: Semantic Clustering

031-040  - Token validation (project-specific rules)
041-050  - MFA-related errors
051-060  - OAuth provider errors
061-070  - SAML errors

Strategy C: Incremental Allocation

031, 032, 033, ... (allocated as needed, documented in catalog)

5.3 Best Practices

Recommended practices:

  • Document the meaning of each sequence in your catalog
  • Use consistent patterns within your project
  • Group related errors together
  • Leave gaps for future expansion

Practices to avoid:

  • Assuming others will understand your custom sequences
  • Using project-specific sequences for common patterns (use 001-030 instead)
  • Allocating sequences randomly without documentation

5.4 Examples

E.Auth.Token.031             - Token rotation failed (custom logic)
E.Payment.Stripe.032         - Stripe webhook signature invalid
E.Inventory.SKU.050          - SKU format specific to your system
E.Shipping.Carrier.075       - Custom carrier validation failed

6. Success/Completion Sequences (998-999)#

6.1 Overview

The final two sequences are reserved for success and completion markers:

6.2 Usage Guidelines

When to use success codes:

Success codes are typically used with positive severities (S=Success, K=Completed, I=Info) to indicate successful operations or completion states.

Examples:

S.Build.Compilation.999      - Build completed successfully
K.Migration.Database.999     - Migration completed
S.Batch.Processing.998       - Batch partially successful (80/100 items)

I.Process.Startup.999        - Startup complete
S.Test.Suite.998             - Tests partially passed (45/50)

6.3 When NOT to Use

Inappropriate uses of 999:

  • Normal operation (use I=Info or T=Trace instead)
  • Expected outcomes (only notable successes)
  • Every successful function call (too verbose)

Appropriate uses of 999:

  • Long-running operations completing
  • Critical milestones reached
  • Batch operations finishing
  • System state transitions

7. Semantic Applicability#

7.1 The Core Principle

Not every sequence applies to every Component.Primary pair.

Domain semantics determine which sequences are meaningful.

7.2 Applicability Matrix

The Combinatorial Space:

WDP error codes are combinatorial—ANY component CAN potentially use ANY sequence—but domain logic constrains which combinations make sense.

Example: Sequence 001 (MISSING)

Broadly applicable:

E.Auth.Token.001         - Token missing
E.Database.Config.001    - Config missing
E.Parser.Input.001       - Input missing
E.FileSystem.File.001    - File path missing
E.Network.Hostname.001   - Hostname missing

Example: Sequence 024 (LOCKED)

Selectively applicable:

Applicable:
E.FileSystem.File.024     - File locked by process
E.Database.Row.024        - Row locked by transaction
E.Thread.Mutex.024        - Mutex already locked

Not applicable:
E.Network.Socket.024      - Sockets don't "lock"
E.Parser.Token.024        - Tokens don't "lock"
E.Auth.Permission.024     - Permissions don't "lock"

7.3 Domain-Specific Questions

Ask yourself:

  1. Does this concept exist in my domain?
    • Can a token "timeout"? (Yes, validation timeout)
    • Can a hash "lock"? (No, hashes are computed, not locked)
  2. Is this the right abstraction level?
    • File handle closed? (Yes, use 013)
    • File data corrupted? (Yes, use 025)
    • File "disconnected"? (No, files don't disconnect)
  3. Is there a better sequence?
    • Session expired: Use 018 (STALE) not 013 (CLOSED)
    • Token expired: Use 018 (STALE) not 017 (TIMEOUT)
    • Connection timeout: Use 017 (TIMEOUT) ✓

7.4 Examples by Component Type

Component: Thread, Primary: Lock

001 MISSING       - Lock object missing // applicable
011 UNINITIALIZED - Lock not initialized // applicable
017 TIMEOUT       - Lock acquisition timeout // applicable
024 LOCKED        - Already locked (deadlock) // applicable
013 CLOSED        - Locks don't "close" // not applicable
029 DISCONNECTED  - Locks don't "disconnect" // not applicable

Component: Network, Primary: Connection

001 MISSING       - Connection string missing // applicable
013 CLOSED        - Connection closed // applicable
017 TIMEOUT       - Connection timeout // applicable
027 UNAVAILABLE   - Service unavailable // applicable
028 UNREACHABLE   - Host unreachable // applicable
029 DISCONNECTED  - Connection dropped // applicable
024 LOCKED        - Connections don't "lock" // not applicable
025 CORRUPTED     - Connections aren't "corrupted" // not applicable

Component: Auth, Primary: Token

001 MISSING       - Token not provided // applicable
003 INVALID       - Token format/signature invalid // applicable
008 DENIED        - Token permissions insufficient // applicable
018 STALE         - Token expired/needs refresh // applicable
013 CLOSED        - Tokens don't "close" // not applicable
024 LOCKED        - Tokens don't "lock" // not applicable
029 DISCONNECTED  - Tokens don't "disconnect" // not applicable

8. Usage Guidelines#

8.1 Decision Process

Step 1: Check if a convention exists

  • Review sequences 001-030 for semantic matches
  • Check if the pattern fits your domain

Step 2: Evaluate semantic fit

  • Ask "Does this make sense for my Component.Primary?"
  • Consider domain-specific terminology

Step 3: Choose appropriately

  • If convention fits: Use it
  • If convention doesn't fit: Use project-specific range (031-897)
  • Don't force a convention that doesn't fit

Step 4: Document your choice

  • Add entry to your error catalog
  • Explain why you chose that sequence
  • Note any deviations from conventions

8.2 Common Patterns

Pattern: "Something is missing"

Use: 001 (MISSING)
Examples:
  E.Auth.Token.001
  E.Config.Database.001
  E.Input.File.001

Pattern: "Operation took too long"

Use: 017 (TIMEOUT)
Examples:
  E.Network.Request.017
  E.Database.Query.017
  E.Lock.Acquisition.017

Pattern: "Resource doesn't exist"

Use: 021 (NOTFOUND)
Examples:
  E.FileSystem.File.021
  E.Database.Record.021
  E.API.Endpoint.021

8.3 Anti-Patterns

Anti-Pattern: Using conventions mechanically

Incorrect:
E.Crypto.Hash.021  - "Hash not found"
// Hashes are computed, not found—use project-specific sequence

Correct:
E.Crypto.Algorithm.009 - "Algorithm unsupported"
// Convention fits: algorithm is unsupported

Anti-Pattern: Forcing semantic mismatch

Incorrect:
E.Memory.Buffer.013 - "Buffer closed"
// Buffers deallocate/free, they don't "close"—use project-specific

Correct:
E.Memory.Buffer.026 - "Buffer exhausted"
// Convention fits: resource exhaustion

Anti-Pattern: Ignoring better matches

Incorrect:
E.Auth.Session.013 - "Session closed"
// Sessions expire, not "close"—better: 018 STALE

Correct:
E.Auth.Session.018 - "Session expired/stale"
// Better semantic match

9. Examples by Domain#

9.1 Authentication Domain

Component: Auth
Primary: Token

001 MISSING         - Token not provided in request
003 INVALID         - Token signature verification failed
008 DENIED          - Token lacks required permissions
018 STALE           - Token expired, refresh needed
031                 - Token rotation failed (project-specific)
032                 - Token revoked in blocklist (project-specific)

9.2 Database Domain

Component: Database
Primary: Connection

001 MISSING         - Connection string not configured
013 CLOSED          - Connection was closed
017 TIMEOUT         - Connection timeout
021 NOTFOUND        - Database not found
027 UNAVAILABLE     - Database temporarily unavailable
028 UNREACHABLE     - Database host unreachable
029 DISCONNECTED    - Connection dropped unexpectedly

9.3 File System Domain

Component: FileSystem
Primary: File

001 MISSING         - File path parameter missing
003 INVALID         - File path format invalid
021 NOTFOUND        - File does not exist
022 ALREADYEXISTS   - File already exists
024 LOCKED          - File locked by another process
025 CORRUPTED       - File data corrupted
026 EXHAUSTED       - Disk full, cannot write

9.4 Network Domain

Component: Network
Primary: Request

001 MISSING         - Request URL missing
003 INVALID         - Request format invalid
017 TIMEOUT         - Request timed out
027 UNAVAILABLE     - Service unavailable (503)
028 UNREACHABLE     - Host unreachable
029 DISCONNECTED    - Connection lost during request

9.5 Success/Completion Domain

Component: Build
Primary: Compilation

998 PARTIAL         - Build partially succeeded (warnings present)
999 COMPLETE        - Build completed successfully

Component: Test
Primary: Suite

998 PARTIAL         - Some tests passed, some failed
999 COMPLETE        - All tests passed

Component: Migration
Primary: Database

999 COMPLETE        - Migration completed successfully

10. Quick Reference#

10.1 Convention Summary Table

10.2 Common Mappings

HTTP Status Codes:

400 Bad Request       → 003 INVALID
401 Unauthorized      → 008 DENIED
403 Forbidden         → 008 DENIED
404 Not Found         → 021 NOTFOUND
409 Conflict          → 022 ALREADYEXISTS or 023 CONFLICT
429 Too Many Requests → 026 EXHAUSTED
503 Service Unavailable → 027 UNAVAILABLE
504 Gateway Timeout   → 017 TIMEOUT

POSIX Errno:

ENOENT (No such file)      → 021 NOTFOUND
EEXIST (File exists)       → 022 ALREADYEXISTS
EACCES (Permission denied) → 008 DENIED
ETIMEDOUT (Timeout)        → 017 TIMEOUT
ENOSPC (No space)          → 026 EXHAUSTED

References#

Normative References

  • STRUCTURE.md - WDP error code structure overview
  • 4-SEQUENCE.md - Sequence field specification (normative)
  • 1-SEVERITY.md - Severity field specification
  • 2-COMPONENT.md - Component field specification
  • 3-PRIMARY.md - Primary field specification

Informative References

  • RFC 2119 - Key words for RFCs
  • RFC 9110 - HTTP Status Codes
  • POSIX errno.h - IEEE Std 1003.1

Document Status#

This document is INFORMATIVE (non-normative).

Conformance to WDP does not require following these conventions. They are provided as guidance to improve consistency and recognizability across projects that choose to adopt them.

End of Sequence Conventions (Informative)