DocumentWDP-6

Version0.1.0-draft

Last Updated2025-12-25

StatusDraft

CategoryInformative (Non-Normative)

WDP Part 6: Sequence Conventions

Recommended sequence number patterns for WDP diagnostics.

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 for WDP compliance. Projects MAY adopt, adapt, or ignore these conventions based on their domain-specific needs.

Note: Sequence conventions are suggestions, not requirements. Domain semantics take precedence over these conventions.

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 the following benefits:

Consistency: Similar errors use similar numbers across projects
Recognition: Developers can recognize common patterns instantly
Predictability: New team members can anticipate 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 versus when to deviate
Examples demonstrating appropriate and inappropriate usage

This document does NOT cover:

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

1.3 Combinatorial Nature#

WDP error codes are combinatorial by design:

ANY Severity × ANY Component × ANY Primary × ANY Sequence

This design implies:

The same sequence number MAY appear in multiple components
Each Component.Primary pair defines its own namespace
Sequence 001 might mean "missing" in one context and something different in another
Conventions suggest common patterns but do not enforce them

2. Conformance Status#

2.1 RFC 2119 Keywords in This Document#

This document uses RFC 2119 keywords with the following interpretations:

Keyword	Interpretation in This Document
MUST	Used only for internal logical consistency (if X, then MUST Y)
SHOULD	Recommended practice; deviation is acceptable with documented rationale
RECOMMENDED	Suggested best practice
MAY	Completely optional, at implementer's discretion

2.2 Conformance Requirements#

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#

Implementations SHOULD deviate from these conventions when:

Domain semantics differ: The domain has different natural groupings
Existing systems: Compatibility with legacy error codes takes precedence
Team preference: The team has established different conventions
Better organization: A more logical structure exists for the domain
Semantic mismatch: The convention does not apply in the given context

Deviations SHOULD be documented in the 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:

Range	Purpose	Status
001-030	Reserved semantic patterns	RECOMMENDED conventions
031-897	Project-specific codes	No conventions
998-999	Success/completion markers	RECOMMENDED conventions

3.2 Reserved Semantic Ranges (001-030)#

The first 30 sequences are organized by error category:

Range	Category	Examples
001-010	Input/Data Validation	Missing, Invalid, Mismatch
011-020	State/Lifecycle	Uninitialized, Closed, Timeout
021-030	Resource/Storage	NotFound, Conflict, Exhausted

3.3 Rationale#

The reserved ranges were selected based on the following criteria:

Frequency: These patterns occur in most software systems
Recognition: Common enough to be memorable
Flexibility: Broad enough to cover many use cases
Limited scope: Only 30 reserved numbers, leaving 867 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.

Sequence	Semantic	Description	When to Use
001	MISSING	Required data not provided	Parameter missing, field empty, resource not supplied
002	MISMATCH	Type or length mismatch	Type error, size mismatch, format disagreement
003	INVALID	Validation check failed	Format invalid, checksum failed, constraint violated
004	OVERFLOW	Value too large	Buffer overflow, numeric overflow, size exceeded
005	UNDERFLOW	Value too small	Buffer underflow, numeric underflow, below minimum
006	OUTOFBOUNDS	Outside valid range	Index out of bounds, value outside range
007	DUPLICATE	Duplicate entry	Unique constraint violation, duplicate key
008	DENIED	Permission denied	Authorization failed, access forbidden
009	UNSUPPORTED	Feature not supported	Unsupported operation, not implemented
010	DEPRECATED	Feature deprecated	Deprecated API, obsolete feature (warning)

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.

Sequence	Semantic	Description	When to Use
011	UNINITIALIZED	Not initialized	Object not initialized, setup incomplete
012	ALREADYINIT	Already initialized	Double initialization attempted
013	CLOSED	Resource closed	Connection closed, file closed, stream ended
014	CANCELLED	Operation cancelled	User cancelled, timeout cancelled, abort requested
015	INPROGRESS	Already in progress	Operation already running, duplicate action
016	NOTREADY	Not ready	Precondition not met, dependencies unavailable
017	TIMEOUT	Operation timed out	Deadline exceeded, response timeout
018	STALE	Resource stale	Cache stale, data outdated, session expired
019	(reserved)	(future use)
020	(reserved)	(future use)

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.

Sequence	Semantic	Description	When to Use
021	NOTFOUND	Resource not found	File not found, record missing, endpoint 404
022	ALREADYEXISTS	Resource already exists	File exists, duplicate key, conflict 409
023	CONFLICT	Version or data conflict	Optimistic lock failed, merge conflict
024	LOCKED	Resource locked	File locked, row locked, mutex held
025	CORRUPTED	Data corrupted	Checksum failed, integrity error, malformed data
026	EXHAUSTED	Resource exhausted	Out of memory, disk full, quota exceeded
027	UNAVAILABLE	Temporarily unavailable	Service down, maintenance mode, circuit breaker open, or classification unavailable for wrapped external errors
028	UNREACHABLE	Cannot reach resource	Network unreachable, DNS failed, host down
029	DISCONNECTED	Connection lost	Network dropped, peer disconnected
030	(reserved)	(future use)

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 the project catalog
Use consistent patterns within the project
Group related errors together
Leave gaps for future expansion

Practices to avoid:

Assuming others will understand custom sequences without documentation
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:

Sequence	Semantic	Description	When to Use
998	PARTIAL	Partial success	Some items succeeded, some failed
999	COMPLETE	Full success	All operations completed successfully

6.2 Usage Guidelines#

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 (reserve for notable successes only)
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 Core Principle#

Not every sequence applies to every Component.Primary pair. Domain semantics determine which sequences are meaningful.

7.2 Applicability Matrix#

WDP error codes are combinatorial: any component MAY potentially use any sequence. However, domain logic constrains which combinations are semantically meaningful.

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 Considerations#

When selecting a sequence, consider the following questions:

Does this concept exist in the domain?
- Can a token "timeout"? (Yes, validation timeout)
- Can a hash "lock"? (No, hashes are computed, not locked)
Is this the appropriate abstraction level?
- File handle closed? (Yes, use 013)
- File data corrupted? (Yes, use 025)
- File "disconnected"? (No, files do not disconnect)
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

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

Component: Network, Primary: Connection

MISSING       - Connection string missing // applicable
CLOSED        - Connection closed // applicable
TIMEOUT       - Connection timeout // applicable
UNAVAILABLE   - Service unavailable // applicable
UNREACHABLE   - Host unreachable // applicable
DISCONNECTED  - Connection dropped // applicable
LOCKED        - Connections don't "lock" // not applicable
CORRUPTED     - Connections aren't "corrupted" // not applicable

Component: Auth, Primary: Token

MISSING       - Token not provided // applicable
INVALID       - Token format/signature invalid // applicable
DENIED        - Token lacks required permissions // applicable
STALE         - Token expired/needs refresh // applicable
CLOSED        - Tokens don't "close" // not applicable
LOCKED        - Tokens don't "lock" // not applicable
DISCONNECTED  - Tokens don't "disconnect" // not applicable

Component: FileSystem, Primary: File

MISSING       - File path parameter missing // applicable
NOTFOUND      - File doesn't exist // applicable
ALREADYEXISTS - File already exists // applicable
LOCKED        - File locked by process // applicable
CORRUPTED     - File data corrupted // applicable
CLOSED        - Files are opened/closed, but error is about the file itself // not applicable
DISCONNECTED  - Files 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
Evaluate whether the pattern fits the domain

Step 2: Evaluate semantic fit

Determine if the convention makes sense for the Component.Primary pair
Consider domain-specific terminology

Step 3: Choose appropriately

If the convention fits: Use it
If the convention does not fit: Use project-specific range (031-897)
Do not force a convention that does not apply

Step 4: Document the choice

Add an entry to the error catalog
Explain the rationale for the sequence selection
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

Pattern: "Resource already exists"

Use: 022 (ALREADYEXISTS)
Examples:
  E.FileSystem.File.022
  E.Database.Key.022
  E.User.Account.022

Pattern: "Service temporarily unavailable"

Use: 027 (UNAVAILABLE)
Examples:
  E.Database.Connection.027
  E.Cache.Server.027
  E.API.Service.027

8.3 Anti-Patterns#

Anti-Pattern: Mechanical application of conventions

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 do not "close". Use project-specific sequence.

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; they do not "close". Better: 018 STALE

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

8.4 Handling Unclassified Errors#

WDP does not define a global "Unknown" sequence. When wrapping external errors or encountering unclassifiable conditions, implementations SHOULD scope to the most specific Component.Primary known and use sequence 027 (UNAVAILABLE) to indicate that proper classification is unavailable.

Rationale:

A global E.Unknown.Unknown.001 provides no actionable information
Scoping to Component.Primary ensures errors are at least localized to a subsystem
Sequence 027 (UNAVAILABLE) semantically indicates "proper classification unavailable"
Original error details preserved in dynamic fields enable debugging

Pattern: Unclassified external error

Use: 027 (UNAVAILABLE) with original error in payload
Examples:
  E.External.Oracle.027    - Unclassified Oracle error
  E.External.AWS.027       - Unclassified AWS error
  E.External.Vendor.027    - Unclassified third-party error
  E.Database.Internal.027  - Unclassified internal database error

Example with dynamic fields:

Implementations SHOULD use the standardized cause object to preserve original error details:

{
  "code": "E.External.Oracle.027",
  "compact_id": "KvGUF",
  "message": "Oracle error: {{cause_message}}",
  "fields": {
    "cause_code": "ORA-12154",
    "cause_message": "TNS:could not resolve the connect identifier specified",
    "cause_type": "DatabaseError"
  }
}

Recommended cause_* field names:

Field	Description	Example
cause_code	Original error code from external system	"ORA-12154", "ECONNREFUSED", "500"
cause_message	Original error message	"TNS:could not resolve..."
cause_type	Original error type/class	"DatabaseError", "IOException"

Alternatively, implementations MAY use a nested cause object in the wire protocol (see 9b-WIRE-PROTOCOL.md).

Anti-Pattern: Global Unknown

Incorrect:
E.Unknown.Unknown.001     - "Unknown error occurred"
// Provides no context; impossible to debug or route

Correct:
E.External.Oracle.027     - Oracle error with original details in payload
// Scoped to subsystem; original error preserved for debugging

9. Examples by Domain#

9.1 Authentication Domain#

Component: Auth
Primary: Token

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

9.2 Database Domain#

Component: Database
Primary: Connection

MISSING         - Connection string not configured
CLOSED          - Connection was closed
TIMEOUT         - Connection timeout
NOTFOUND        - Database not found
UNAVAILABLE     - Database temporarily unavailable
UNREACHABLE     - Database host unreachable
DISCONNECTED    - Connection dropped unexpectedly

9.3 File System Domain#

Component: FileSystem
Primary: File

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

9.4 Network Domain#

Component: Network
Primary: Request

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

9.5 Parser Domain#

Component: Parser
Primary: Syntax

MISSING         - Required syntax element missing
INVALID         - Syntax rule violated
OUTOFBOUNDS     - Token outside valid grammar
               - Unexpected end of input (project-specific)
               - Unterminated string literal (project-specific)

9.6 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#

Sequence	Semantic	Use When...
001	MISSING	Required data not provided
002	MISMATCH	Type/length mismatch
003	INVALID	Validation failed
004	OVERFLOW	Value too large
005	UNDERFLOW	Value too small
006	OUTOFBOUNDS	Outside valid range
007	DUPLICATE	Duplicate entry
008	DENIED	Permission denied
009	UNSUPPORTED	Feature not supported
010	DEPRECATED	Feature deprecated
011	UNINITIALIZED	Not initialized
012	ALREADYINIT	Already initialized
013	CLOSED	Resource closed
014	CANCELLED	Operation cancelled
015	INPROGRESS	Already in progress
016	NOTREADY	Not ready
017	TIMEOUT	Operation timed out
018	STALE	Resource stale/expired
021	NOTFOUND	Resource not found
022	ALREADYEXISTS	Resource already exists
023	CONFLICT	Version/data conflict
024	LOCKED	Resource locked
025	CORRUPTED	Data corrupted
026	EXHAUSTED	Resource exhausted
027	UNAVAILABLE	Temporarily unavailable
028	UNREACHABLE	Cannot reach
029	DISCONNECTED	Connection lost
031-897	(project-specific)	Your custom errors
998	PARTIAL	Partial success
999	COMPLETE	Full success

10.2 Common Mappings#

HTTP Status Codes:

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