WDP Part 7: Namespaces and Error Boundaries

my_app/
  ├─ uses auth_lib → E.Auth.Token.001
  ├─ uses payment_lib → E.Auth.Token.001  (identical code)
  └─ logs show: [E.Auth.Token.001] → source indeterminate

UI → calls user_service → E.Database.Connection.021
UI → calls order_service → E.Database.Connection.021 (identical code)
UI receives: {"h":"Xy8Qz"} → source indeterminate

Error Boundary := A named scope B where all error codes within B are unique

Within boundary B:
  - E.Auth.Token.001 ≠ E.Auth.Token.002 (distinct codes)
  - E.Auth.Token.001 ≠ E.Database.Query.017 (distinct codes)
  
Across boundaries B1 and B2:
  - B1:E.Auth.Token.001 is distinct from B2:E.Auth.Token.001
  - Identical structured code, distinct context

Error Boundary (abstract concept)
        ↓
Namespace (concrete implementation)

namespace:SEVERITY.COMPONENT.PRIMARY.SEQUENCE -> namespace_hash-code_hash

auth_lib:E.Auth.Token.001 -> 05o5h-V6a0B

Rust crate:     tokio, serde, auth_lib
NPM package:    express → express (or my_org_express if namespaced)
Python package: django, flask, user_auth
Maven artifact: com.acme.auth → acme_auth
Service:        user_service, payment_gateway
Application:    my_app, waddling_lang_tool

Step 1: Encode namespace as UTF-8 bytes
  "auth_lib" → [0x61, 0x75, 0x74, 0x68, 0x5F, 0x6C, 0x69, 0x62]

Step 2: Compute hash using xxHash3
  hash_value = xxh3_64(bytes, seed=0x31762D736E706477)

Step 3: Extract 40 bits (bytes 3-7) and encode as Base62 (5 characters)
  Base62(hash_value[3:8]) → "05o5h"

Error code seed:  "wdp-v1"   (0x000031762D706477)
Namespace seed:   "wdpns-v1" (0x31762D736E706477)

This separation ensures:
  hash("auth_lib", "wdpns-v1") ≠ hash("E.AUTH.TOKEN.001", "wdp-v1")

namespace:SEVERITY.COMPONENT.PRIMARY.SEQUENCE -> namespace_hash-code_hash
│          │        │         │        │          │             │
│          │        │         │        │          │             └─ Part 5: Code hash
│          │        │         │        │          └─────────────── Namespace hash
│          │        │         │        └─────────────────────────  Part 4: Sequence
│          │        │         └──────────────────────────────────  Part 3: Primary
│          │        └────────────────────────────────────────────  Part 2: Component
│          └─────────────────────────────────────────────────────  Part 1: Severity
└────────────────────────────────────────────────────────────────  Part 0: Namespace

Format: namespace_hash-code_hash
Example: 05o5h-V6a0B

Components:
  - namespace_hash: 5 Base62 characters
  - separator: single hyphen '-'
  - code_hash: 5 Base62 characters
  
Total length: 11 characters

Input: "05o5h-V6a0B"

if contains single '-':
    parts = split('-')
    namespace_hash = parts[0]  # "05o5h"
    code_hash = parts[1]       # "V6a0B"
else:
    # Legacy format (no namespace)
    namespace_hash = None
    code_hash = input          # "V6a0B"

Without namespace (5-part):
  [E.Auth.Token.001] -> V6a0B
  Valid; no namespace required

With namespace (6-part):
  auth_lib:[E.Auth.Token.001] -> 05o5h-V6a0B
  Provides global context; core code remains unchanged

Namespace: auth_lib

E.Auth.Token.001      ← Unique
E.Auth.Token.002      ← Unique (distinct from 001)
E.Auth.Session.001    ← Unique (distinct component.primary)
W.Auth.Token.001      ← Unique (distinct severity)

Namespace: auth_lib
  E.Auth.Token.001 → "Authentication token missing"

Namespace: payment_lib  
  E.Auth.Token.001 → "Payment authorization token missing"

auth_lib:E.Auth.Token.001 → 05o5h-V6a0B
payment_lib:E.Auth.Token.001 → k9Xmq-V6a0B
                                 ^^^^^^^^^^ Distinct identifiers

// Rust crate: auth-lib
pub const NAMESPACE: &str = "auth_lib";

# Kubernetes service
metadata:
  name: user-service
wdp:
  namespace: user_service

// package.json
{
  "name": "my-app",
  "wdp": {
    "namespace": "my_app"
  }
}

Option A: Shared namespace (RECOMMENDED)
  auth_lib_core → namespace: auth_lib
  auth_lib_jwt → namespace: auth_lib
  (All errors under one boundary)

Option B: Separate namespaces
  auth_lib_core → namespace: auth_lib_core
  auth_lib_jwt → namespace: auth_lib_jwt
  (Independent error spaces)

^[a-z][a-z0-9_]{0,31}$

a                    // valid: 1 character minimum
auth_lib             // valid: typical library name
user_service         // valid: typical service name
waddling_lang_tool   // valid: 18 characters
my_app_v2            // valid: with version suffix, if necessary
tokio                // valid: concise, well-known name
acme_payment_gateway // valid: 20 characters

Auth_lib            // invalid: uppercase characters not permitted
auth-lib            // invalid: hyphen not permitted
auth.lib            // invalid: period not permitted
auth/lib            // invalid: slash not permitted
_auth_lib           // invalid: MUST NOT start with underscore
2auth_lib           // invalid: MUST NOT start with digit
auth lib            // invalid: space not permitted
this_is_a_very_long_namespace_name // invalid: 33 characters exceeds maximum

fn is_valid_namespace(ns: &str) -> bool {
    if ns.is_empty() || ns.len() > 32 {
        return false;
    }
    
    let mut chars = ns.chars();
    
    // First character must be lowercase letter
    if !matches!(chars.next(), Some('a'..='z')) {
        return false;
    }
    
    // Remaining characters must be lowercase letter, digit, or underscore
    chars.all(|c| matches!(c, 'a'..='z' | '0'..='9' | '_'))
}

assert!(is_valid_namespace("auth_lib"));
assert!(!is_valid_namespace("Auth_lib"));
assert!(!is_valid_namespace("auth-lib"));

// Define namespace constant
pub const NAMESPACE: &str = "auth_lib";

// Use in error definitions
#[derive(WdpError)]
#[wdp(namespace = "auth_lib")]
pub enum AuthError {
    #[wdp(code = "E.Auth.Token.001")]
    TokenMissing,
    
    #[wdp(code = "E.Auth.Token.018")]
    TokenExpired,
}

// Generated methods
impl AuthError {
    pub fn namespace(&self) -> &str {
        NAMESPACE
    }
    
    pub fn full_code(&self) -> String {
        format!("{}:{}", NAMESPACE, self.code())
    }
    
    pub fn full_id(&self) -> String {
        format!("{}-{}", 
            namespace_hash(NAMESPACE), 
            self.compact_id()
        )
    }
}

# service-config.yml
service:
  name: user-service
  wdp:
    namespace: user_service
    catalog: /etc/wdp/user_service_catalog.json

// Initialize with multiple namespaces
import { registerNamespace } from '@wdp/core';

// Register dependencies
registerNamespace('auth_lib');
registerNamespace('payment_lib');
registerNamespace('my_app');

// Errors carry namespace
const error = new WdpError({
  namespace: 'my_app',
  code: 'E.Application.Startup.001',
});

console.log(error.fullCode());  // "my_app:E.Application.Startup.001"
console.log(error.fullId());     // "pQ7Zw-mN3Yr"

# routing-config.yml
namespaces:
  user_service:
    team: "User Team"
    slack: "#user-service-alerts"
    pagerduty: "user-service-oncall"
    
  payment_lib:
    team: "Payment Team"
    slack: "#payment-alerts"
    pagerduty: "payment-oncall"

fn route_error(error: &WdpError) {
    let config = ROUTING_CONFIG.get(error.namespace())?;
    
    match error.severity() {
        Severity::Error | Severity::Critical => {
            page_oncall(config.pagerduty);
            post_to_slack(config.slack, error);
        }
        _ => log_only(error),
    }
}

// Smart catalog loading
async function expandError(compactId) {
    const [nsHash, codeHash] = compactId.split('-');
    
    // Resolve namespace from hash
    const namespace = await resolveNamespace(nsHash);
    
    // Load only the required catalog
    const catalog = await loadCatalog(namespace);
    
    // Expand error
    return catalog.lookup(codeHash);
}

-- Group errors by namespace
SELECT namespace, COUNT(*) as error_count
FROM error_logs
WHERE timestamp > NOW() - INTERVAL '1 hour'
GROUP BY namespace
ORDER BY error_count DESC;

-- Namespace-specific SLA monitoring
SELECT 
  namespace,
  COUNT(*) FILTER (WHERE severity = 'E') as error_count,
  COUNT(*) as total_count,
  (COUNT(*) FILTER (WHERE severity = 'E')::float / COUNT(*)) as error_rate
FROM logs
WHERE timestamp > NOW() - INTERVAL '1 day'
GROUP BY namespace
HAVING error_rate > 0.01;  -- Alert if > 1% error rate

[E.Parser.Argument.001] -> V6a0B

error: Expected 'domain' keyword
   --> state.travel:10:5

[E.Parser.Argument.001] -> 05o5h-V6a0B
namespace: waddling_lang_tool

error: Expected 'domain' keyword
  --> state.travel:10:5

{
  "level": "error",
  "namespace": "waddling_lang_tool",
  "code": "E.Parser.Argument.001",
  "compact_id": "V6a0B",
  "namespace_hash": "05o5h",
  "full_id": "05o5h-V6a0B",
  "message": "Expected 'domain' keyword"
}

Without namespace (Level 0-1):
  [E.Auth.Token.001] -> V6a0B

With namespace (Level 4):
  auth_lib:[E.Auth.Token.001] -> 05o5h-V6a0B

auth_lib:E.Auth.Token.001  (001 = MISSING, per convention)
auth_lib:E.Auth.Token.018  (018 = STALE, per convention)

payment_lib:E.Auth.Token.001  (also MISSING, same convention)

Namespace: auth_lib (fixed)
Language: en, es, ja (varies)

English:  auth_lib:E.Auth.Token.001 -> "Token missing"
Spanish:  auth_lib:E.Auth.Token.001 -> "Token faltante"
Japanese: auth_lib:E.Auth.Token.001 -> "トークンがありません"

catalogs/
  ├─ auth_lib_catalog.json
  ├─ payment_lib_catalog.json
  └─ user_service_catalog.json

{
  "namespace": "auth_lib",
  "namespace_hash": "05o5h",
  "errors": { ... }
}

acme_corp_v2_payment_gateway_production_service_auth_module_v3
  (Too long, unclear, poor naming)

acme_payment_gateway
  (Concise, clear, descriptive)

Library error:
  auth_lib:E.Auth.Token.001 -> 05o5h-V6a0B

Service error:
  user_service:E.Database.Query.017 -> pQ7Zw-kN8Qz

Application error:
  waddling_lang_tool:E.Parser.Syntax.003 -> mN3Yr-xY9Kp

// Application with multiple dependencies

// Dependency 1: auth_lib
let auth_error = auth_lib::TokenMissing;
assert_eq!(auth_error.full_code(), "auth_lib:E.Auth.Token.001");
assert_eq!(auth_error.full_id(), "05o5h-V6a0B");

// Dependency 2: payment_lib (same code structure!)
let payment_error = payment_lib::TokenMissing;
assert_eq!(payment_error.full_code(), "payment_lib:E.Auth.Token.001");
assert_eq!(payment_error.full_id(), "k9Xmq-V6a0B");  // Different hash!

// No collision - namespace disambiguates
assert_ne!(auth_error.full_id(), payment_error.full_id());

┌──────────────┐    E.Database.Query.017    ┌──────────────┐
│ user_service │ ─────────────────────────> │  API Gateway │
└──────────────┘                            └──────────────┘
                                                     │
                                                     ├─ Parse namespace
                                                     ├─ user_service → User Team
                                                     └─ Route to #user-service-alerts

┌────────────────┐   E.Database.Query.017     ┌──────────────┐
│ order_service  │ ─────────────────────────> │  API Gateway │
└────────────────┘                            └──────────────┘
                                                     │
                                                     ├─ Parse namespace
                                                     ├─ order_service → Order Team
                                                     └─ Route to #order-service-alerts

Pattern:   [a-z][a-z0-9_]{0,31}
Regex:     ^[a-z][a-z0-9_]{0,31}$
Length:    1-32 characters
Required:  NO (optional extension)

Algorithm: xxHash3 (xxh3_64)
Seed:      "wdpns-v1" (0x31762D736E706477)
Encoding:  Base62
Length:    5 characters

Full code:    namespace:SEVERITY.COMPONENT.PRIMARY.SEQUENCE
Full hash:    namespace_hash-code_hash
Example code: auth_lib:E.Auth.Token.001
Example hash: 05o5h-V6a0B