WDP Part 7: Namespaces and Error Boundaries

my_app/
  ├─ uses auth_lib → E.Auth.Token.001
  ├─ uses payment_lib → E.Auth.Token.001  (same code!)
  └─ logs show: [E.Auth.Token.001] → which library?

UI → calls user_service → E.Database.Connection.021
UI → calls order_service → E.Database.Connection.021 (same code!)
UI sees: {"h":"Xy8Qz"} → which service?

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 (different codes)
  - E.Auth.Token.001 ≠ E.Database.Query.017 (different codes)
  
Across boundaries B1 and B2:
  - B1:E.Auth.Token.001 is distinct from B2:E.Auth.Token.001
  - Same structured code, different context

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

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

auth_lib:E.Auth.Token.001 -> h4tYw2-81E9g

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: Hash with xxHash64
  hash_value = xxHash64(bytes, seed="wdp-ns-v1")

Step 3: Encode as Base62 (5 characters, left-padded with '0' if needed)
  Base62(hash_value) → "h4tYw2"

Error code seed:  "wdp-v1"
Namespace seed:   "wdp-ns-v1"

Prevents:
  hash("auth_lib", "wdp-ns-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: h4tYw2-81E9g

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

Input: "h4tYw2-81E9g"

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

Without namespace (5-part):
  [E.Auth.Token.001] -> 81E9g
  Valid, no namespace required

With namespace (6-part):
  auth_lib:[E.Auth.Token.001] -> h4tYw2-81E9g
  Adds global context, core code unchanged

Namespace: auth_lib

E.Auth.Token.001      ← Unique
E.Auth.Token.002      ← Unique (different from 001)
E.Auth.Session.001    ← Unique (different component.primary)
W.Auth.Token.001      ← Unique (different 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 → h4tYw2-81E9g
payment_lib:E.Auth.Token.001 → k9Xmq-81E9g
                                 ^^^^^^^^^^ Different!

// 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 char minimum
auth_lib             // valid: typical library name
user_service         // valid: typical service name
waddling_lang_tool   // valid: 18 chars
my_app_v2            // valid: with version, if truly needed
tokio                // valid: short, well-known name
acme_payment_gateway // valid: 31 chars - near limit

Auth_lib            // invalid: uppercase not allowed
auth-lib            // invalid: hyphen not allowed
auth.lib            // invalid: period not allowed
auth/lib            // invalid: slash not allowed
_auth_lib           // invalid: cannot start with underscore
2auth_lib           // invalid: cannot start with digit
auth lib            // invalid: space not allowed
this_is_a_very_long_namespace_name // invalid: 33 chars - too long

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] -> 81E9g

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

❌ [E.Parser.Argument.001] -> h4tYw2-81E9g
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": "81E9g",
  "namespace_hash": "h4tYw2",
  "full_id": "h4tYw2-81E9g",
  "message": "Expected 'domain' keyword"
}

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

With namespace (Level 4):
  auth_lib:[E.Auth.Token.001] -> h4tYw2-81E9g

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": "h4tYw2",
  "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 -> h4tYw2-81E9g

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(), "h4tYw2-81E9g");

// 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-81E9g");  // 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: xxHash64
Seed:      "wdp-ns-v1"
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: h4tYw2-81E9g