Utilities

1. Purpose & Motivation

Problem Solved

Every C++ project requires common infrastructure for fundamental operations: logging, error handling, unique identifier generation, string manipulation, and encoding. Implementing these utilities from scratch in each domain creates:

  1. Code duplication - Same logging logic repeated across components
  2. Inconsistency - Different error formats, logging styles, UUID implementations
  3. Platform fragmentation - Windows vs Unix differences handled multiple times
  4. Maintenance burden - Bug fixes must propagate to multiple implementations
  5. Integration complexity - Incompatible abstractions prevent code reuse

The Utilities domain solves these problems by providing a centralized, cross-platform foundation that all Viper domains depend on.

Use Cases

Developers use Utilities when they need to:

  1. Generate unique identifiers - UUIds for concept instances, commit IDs, namespace IDs (RFC 4122 compliant)
  2. Log application events - Configurable logging with 6 severity levels (All=0 to Critical=50) and multiple backends (Console, Report, Null)
  3. Handle errors consistently - Structured exceptions with distributed system context (hostname, process, component, domain, code)
  4. Encode binary data - Base64 encoding for text-based protocols (JSON, XML, HTTP headers)
  5. Compare values - Unified ternary comparison returning Ordered enum (Same, Ascending, Descending)
  6. Manipulate strings - C++ internal utilities (split, join, case conversion, enum to string)
  7. Qualify names - Namespace-scoped identifiers for DSM definitions (Tuto::Concept)
  8. Track versions - Compile-time version constants for runtime/ABI compatibility

Position in Architecture

Foundation Layer 0 - Zero dependencies, universally used.

┌─────────────────────────────────────────────────────────────────┐
│                    Application Layer                            │
│  (User code using Viper for data modeling, persistence, etc.)  │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
┌──────────────────────────┐  ┌──────────────────────────┐
│  Functional Layer 1      │  │  Functional Layer 1      │
│  (Database, Commit,      │  │  (DSM, Function Pools,   │
│   RPC/Remote, Services)  │  │   Path, HTML, JSON)      │
└──────────────────────────┘  └──────────────────────────┘
                    │                   │
                    └─────────┬─────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│              Foundation Layer 0 (Utilities)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │  UUId    │  │  Error   │  │ Logging  │  │NameSpace │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │  Base64  │  │ Compare  │  │  String  │  │ Version  │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
└─────────────────────────────────────────────────────────────────┘
                              │
                    ┌─────────┴─────────┐
                    ▼                   ▼
          ┌──────────────┐      ┌──────────────┐
          │  Windows     │      │  Unix/Linux  │
          │  (GUID, RPC) │      │  (uuid_t)    │
          └──────────────┘      └──────────────┘

Critical characteristics:

  • Zero Viper dependencies: Utilities use only std C++ and OS APIs
  • Universally used: 112+ Viper files include Error, UUId, or NameSpace headers
  • Cross-platform: Abstracts Windows (GUID, RPC) vs Unix (uuid_t, POSIX) differences
  • Unidirectional dependency: All domains → Utilities (never reverse)

Utilities enable all higher-layer domains to focus on their specific functionality (persistence, event sourcing, parsing) without reimplementing common infrastructure.

2. Domain Overview

Scope

The Utilities domain provides foundational capabilities for:

  1. Unique Identification - RFC 4122 UUID generation and validation (UUId, NameSpace)
  2. Error Management - Structured exceptions with distributed system context (Error)
  3. Logging Infrastructure - 6-level configurable logging with pluggable backends (Logging, Logger, LoggerConsole, LoggerReport, LoggerNull)
  4. Binary Encoding - RFC 4648 Base64 encoding/decoding (Base64 namespace)
  5. Value Comparison - Ternary comparison interface (Compare template, Ordered enum)
  6. String Manipulation - C++ internal utilities (StringHelper namespace)
  7. Time Access - Current timestamp retrieval (TimeHelper namespace)
  8. Version Information - Compile-time version constants (Version macros)

Scope boundaries: - ✅ In scope: Cross-platform abstractions, common patterns (Singleton, Factory, Strategy), lightweight utilities - ❌ Out of scope: Application-specific logic, heavy frameworks (no Boost dependencies), GUI utilities

Key Concepts

  1. Cross-Platform Adapter Pattern (UUId) - Wraps platform-specific APIs (Windows GUID vs Unix uuid_t) with unified C++ interface and byte-order normalization

  2. Structured Error with Context (Error) - Exceptions carry distributed system metadata (hostname, process, component, domain, code) in parseable format [process@host]:component:domain:code:message

  3. Strategy Pattern for Logging (Logging interface) - Abstract log(level, message) interface with concrete implementations (Console stdout, Report in-memory, Null silent) and level filtering (All=0 to Critical=50)

  4. Singleton Pattern (UUId::Invalid, NameSpace::Global) - Pre-allocated constants for nil UUID (00000000-0000-0000-0000-000000000000) and root namespace

  5. Stateless Utility Namespaces (Base64, StringHelper, TimeHelper) - Pure functions with no state, header-only or minimal implementation, zero allocation overhead

  6. Value Semantics (UUId, NameSpace) - Copyable, comparable, hashable types suitable for std::map keys and value-based programming

External Dependencies

Uses (Platform APIs): - Windows: GUID generation (UuidCreate), RPC string conversion (UuidToStringA), hostname (gethostname) - Unix/Linux: uuid_t generation (uuid_generate), POSIX hostname, <uuid/uuid.h> library - Cross-platform: std C++ only (no Boost, no Qt)

Used By (All Viper Domains): - 112+ C++ files include UUId, Error, or NameSpace headers - Type & Value System - UUId values (TypeUUId, ValueUUId), Compare interface (Ordered) - Commit System - CommitId (UUId wrapper), Error handling, Logging - Database - Error handling, Logging, NameSpace for schema definitions - DSM - NameSpace for qualified names (Tuto::Concept), UUId for runtime IDs, StringHelper for parsing - Blob Storage - Base64 encoding (ValueBlob.base64_encode()), Error handling - Stream/Codec - Error handling, StringHelper for enum to string - RPC/Remote - Error serialization/deserialization, UUId for packet IDs - Function Pools - NameSpace for pool identification, Error handling - Path System - Error handling, Compare for path ordering - JSON Support - Base64 for binary data in JSON, Error handling - HTML - StringHelper for HTML escaping, representation formatting

Dependency Graph:

All Domains (112+ files)
       │
       │ #include "Viper_UUId.hpp"
       │ #include "Viper_Error.hpp"
       │ #include "Viper_NameSpace.hpp"
       │ #include "Viper_Logging.hpp"
       │ #include "Viper_Base64.hpp"
       │ #include "Viper_Compare.hpp"
       ▼
┌──────────────┐
│  Utilities   │  → Windows (GUID, RPC)
│  (Layer 0)   │  → Unix (uuid_t, POSIX)
└──────────────┘  → std C++ (no external dependencies)

Critical insight: Utilities is the only Layer 0 domain with zero Viper dependencies. All other domains (even Type System, Hash System) indirectly use Utilities through Error or UUId.

3. Functional Decomposition

3.1 Sub-domains

1. Core Identity (UUId, NameSpace, Version)

Provides unique identification and namespace management for Viper types and instances.

  • UUId - RFC 4122 UUID generation, parsing, validation (cross-platform: Windows GUID ↔ Unix uuid_t with byte swapping)
  • NameSpace - UUID + name pairs for DSM namespace qualification (Tuto::Concept, ::Global)
  • Version - Compile-time constants for Viper version (VIPER_VERSION_MAJOR=1, MINOR=2, PATCH=0)

Key pattern: Singleton (UUId::Invalid(), NameSpace::Global()), Factory (UUId::create(), UUId::parse()), Value semantics (copyable, comparable, hashable)

Usage: Commit IDs, concept instance IDs, namespace runtime IDs, ABI compatibility checks

2. Logging System (Logging, Logger, Logger{Console,Report,Null})

Configurable logging infrastructure with 6 severity levels and pluggable backends.

  • Logging - Abstract interface with log(level, message) pure virtual method
  • Logger - Template Method base class with level filtering (level member filters messages < level)
  • LoggerConsole - Real-time stdout logging (development, CLI tools)
  • LoggerReport - In-memory message capture (messages() returns vector for test assertions)
  • LoggerNull - Silent logger (Null Object pattern for tests, zero overhead)

Key pattern: Strategy (pluggable backends), Template Method (Logger filters before print), Null Object (LoggerNull)

6 Levels: All=0, Debug=10, Info=20, Warning=30, Error=40, Critical=50 (higher = more severe)

Usage: Application logging (production: WARNING+, development: DEBUG+), test assertions (LoggerReport), silent mode (LoggerNull)

3. Error Handling (Error)

Structured exception class with distributed system context for RPC error propagation.

  • Error - Final class inheriting std::exception with structured fields (hostName, processName, component, domain, code, message)
  • Format: [processName@hostName]:component:domain:code:message
  • Factory: Error::make() captures hostname + PID automatically
  • Parser: Error::parse() deserializes RPC error strings

Key pattern: Factory (auto-capture context), Structured Exception (parseable format), RPC Serialization

Usage: All Viper exceptions use Error, RPC transmits errors across processes, debugging identifies error origin machine

4. Encoding (Base64)

RFC 4648 Base64 encoding/decoding for binary-to-text conversion.

  • Base64::encode(Blob) - Blob → Base64 string (~5MB/s)
  • Base64::decode(string) - Base64 string → Blob
  • Python: ValueBlob.base64_encode(), ValueBlob.base64_decode()

Key pattern: Stateless Namespace (no class, no state, pure functions)

Usage: JSON binary fields, HTTP headers, text protocol interop, ValueBlob Python API

5. Comparison (Compare)

Unified ternary comparison returning Ordered enum (Same, Ascending, Descending).

  • Compare(a, b) - Template function using == and < operators
  • Ordered - Enum: Same (0), Ascending (-1), Descending (+1)
  • Special case: compare(bool, bool) where false < true

Key pattern: Template Function (header-only), Ordered Enumeration

Usage: Value comparisons (all ValueXXX types have compare() method), sorting, map keys

6. String & Time Helpers (C++ Internal)

C++ utilities for string manipulation and time access (no Python bindings).

StringHelper (30+ functions): - Split/Join: split(s, delimiter), join(container, delimiter) - Case: lower(), upper(), snakeCase(), lowerFirst() - Trim/Replace: trim(), trimLeft(), replaceAll() - Enum to string: str(TypeCode), str(StreamToken), str(PathComponentType), etc. (8 enum types) - Formatting: indent(), truncate(), byteCount(), timeInSec() - Blob conversion: toBlob(), fromBlob()

TimeHelper (minimal): - now() - Returns current timestamp as double (seconds since epoch)

Key pattern: Stateless Namespace (C++ only, no Python exposure)

Usage: Viper internal formatting (HTML rendering, DSM representation, error messages), not exposed to Python (Python has built-in string methods)

3.2 Key Components (Entry Points)

Component Purpose Entry Point File Python Binding
UUId RFC 4122 UUID generation/parsing Viper_UUId.hpp ✅ ValueUUId (TypeUUId)
Error Structured exception with context Viper_Error.hpp ✅ ViperError
Logging Abstract logging interface Viper_Logging.hpp ✅ Logging
Logger Template Method base with filtering Viper_Logger.hpp ❌ (C++ only)
LoggerConsole Real-time stdout logging Viper_LoggerConsole.hpp ✅
LoggerReport In-memory message capture Viper_LoggerReport.hpp ✅
LoggerNull Silent logger (Null Object) Viper_LoggerNull.hpp ✅
NameSpace UUID + name for qualified naming Viper_NameSpace.hpp ✅
Base64 RFC 4648 encoding/decoding Viper_Base64.hpp ✅ Via ValueBlob
Compare Ternary comparison template Viper_Compare.hpp ✅ Via Value.compare()
StringHelper String utilities (30+ functions) Viper_StringHelper.hpp ❌ (C++ internal)
TimeHelper Current timestamp Viper_TimeHelper.hpp ❌ (C++ internal)
Version Version constants Viper_Version.hpp ❌ (compile-time)

Python binding coverage: 7/9 components exposed (UUId, Error, Logging, Loggers, NameSpace, Base64, Compare)

C++ only: Logger base class, StringHelper, TimeHelper, Version (not needed in Python)

3.3 Component Relationships

┌─────────────────────────────────────────────────────────────────┐
│                         Utilities Domain                        │
│                                                                 │
│  ┌──────────────────┐         ┌──────────────────┐             │
│  │  Core Identity   │         │  Error Handling  │             │
│  ├──────────────────┤         ├──────────────────┤             │
│  │ • UUId           │◄────────┤ • Error          │             │
│  │   - create()     │  uses   │   - make()       │             │
│  │   - parse()      │         │   - parse()      │             │
│  │   - Invalid()    │         │   [host@proc]:.. │             │
│  │ • NameSpace      │         └──────────────────┘             │
│  │   - uuid + name  │                                           │
│  │   - Global()     │         ┌──────────────────┐             │
│  │ • Version        │         │ Logging System   │             │
│  │   - 1.2.0        │         ├──────────────────┤             │
│  └──────────────────┘         │ • Logging (ABC)  │             │
│                               │   - log(lv, msg) │             │
│  ┌──────────────────┐         │ • Logger (base)  │             │
│  │  Encoding        │         │   - level filter │             │
│  ├──────────────────┤         ├──────────────────┤             │
│  │ • Base64         │         │ Implementations: │             │
│  │   - encode()     │         │ • LoggerConsole  │             │
│  │   - decode()     │         │ • LoggerReport   │             │
│  │ • ValueBlob API  │         │ • LoggerNull     │             │
│  └──────────────────┘         └──────────────────┘             │
│                                                                 │
│  ┌──────────────────┐         ┌──────────────────┐             │
│  │  Comparison      │         │ String/Time      │             │
│  ├──────────────────┤         ├──────────────────┤             │
│  │ • Compare<T>     │         │ • StringHelper   │             │
│  │   - template     │         │   - 30+ funcs    │             │
│  │ • Ordered enum   │         │   - C++ only     │             │
│  │   Same/Asc/Desc  │         │ • TimeHelper     │             │
│  └──────────────────┘         │   - now()        │             │
│                               └──────────────────┘             │
│                                                                 │
│  Legend:                                                        │
│  ABC = Abstract Base Class                                     │
│  ◄──── = Dependency (uses)                                     │
└─────────────────────────────────────────────────────────────────┘

Key relationships:

  1. Error → UUId: Error doesn't use UUId directly (only hostname + process name strings)
  2. NameSpace → UUId: NameSpace contains UUID member for namespace identity
  3. All components independent: No circular dependencies, minimal coupling
  4. Platform abstraction isolated: UUId wraps GUID/uuid_t, other components platform-agnostic

4. Developer Usage Patterns

4.1 Core Scenarios

Each scenario extracted from real test code, demonstrating practical Utilities usage.

Scenario 1: UUID Generation and Validation

When to use: Generate unique identifiers for concept instances, commit IDs, namespace IDs Test source: test_value_uuid.py:100-130 → TestValueUUIdConstruction

from dsviper import ValueUUId

# Generate new cryptographically random UUID4
uuid = ValueUUId.create()
assert uuid.is_valid()
print(uuid.encoded())  # e.g., "28070da6-909d-41da-a567-fcc838896794"

# Parse existing UUID string
uuid = ValueUUId("28070da6-909d-41da-a567-fcc838896794")
assert uuid.encoded() == "28070da6-909d-41da-a567-fcc838896794"
assert uuid.is_valid()

# Uppercase normalized to lowercase (RFC 4122)
uuid = ValueUUId("AAAABBBB-CCCC-DDDD-EEEE-FFFFFFFFFFFF")
assert uuid.encoded() == "aaaabbbb-cccc-dddd-eeee-ffffffffffff"

# Singleton pattern for invalid/nil UUID
invalid = ValueUUId.INVALID
assert invalid.encoded() == "00000000-0000-0000-0000-000000000000"
assert not invalid.is_valid()
assert ValueUUId.INVALID is ValueUUId.INVALID  # Same instance

# Copy semantics (different objects, equal values)
original = ValueUUId("12345678-1234-1234-1234-123456789abc")
copy = ValueUUId(original)
assert original == copy
assert original is not copy  # Different objects

# Invalid format raises ViperError
try:
    uuid = ValueUUId("not-a-uuid")
except ViperError as e:
    print(e)  # [process@host]:Viper.UUId:UUIdErrors:1:The literal 'not-a-uuid' is a malformed UUId.

Key APIs: ValueUUId.create(), ValueUUId(string), .is_valid(), .encoded(), ValueUUId.INVALID

Scenario 2: Logging with Level Filtering - LoggerConsole

When to use: Real-time console logging for CLI tools, development debugging Test source: test_logging.py:153-171 → TestLoggerConsole::test_logging_interface_access

from dsviper import LoggerConsole, Logging

# Create console logger with INFO level (filters out DEBUG)
logger = LoggerConsole(Logging.LEVEL_INFO)
logging = logger.logging()

# DEBUG message filtered out (< INFO level)
logging.debug("Detailed trace information")  # Not shown

# INFO and higher levels shown on stdout
logging.info("Application started")         # Shown: [INF] Application started
logging.warning("Low disk space")           # Shown: [WNG] Low disk space
logging.error("Connection failed")          # Shown: [ERR] Connection failed
logging.critical("System crash imminent")   # Shown: [CRI] System crash imminent

# Direct log() method with numeric level
logging.log(Logging.LEVEL_WARNING, "Custom warning")  # Shown

# Use case: CLI tool with --verbose flag
import sys
level = Logging.LEVEL_DEBUG if "--verbose" in sys.argv else Logging.LEVEL_INFO
logger = LoggerConsole(level)

Key APIs: LoggerConsole(level), .logging(), .debug(), .info(), .warning(), .error(), .critical(), .log(level, message)

6 Log Levels: - Logging.LEVEL_ALL = 0 - Log everything - Logging.LEVEL_DEBUG = 10 - Detailed debugging - Logging.LEVEL_INFO = 20 - Informational messages - Logging.LEVEL_WARNING = 30 - Warnings - Logging.LEVEL_ERROR = 40 - Errors - Logging.LEVEL_CRITICAL = 50 - Critical failures

Level hierarchy: Higher number = more severe. Logger filters messages with level < logger.level.

Scenario 3: Logging for Tests - LoggerReport

When to use: Test assertions on logged messages, debugging with post-mortem analysis Test source: test_logging.py:370-410 → TestLoggerReport::test_messages_captured_in_order

from dsviper import LoggerReport, Logging

# Create report logger with WARNING level (captures WARNING+)
logger = LoggerReport(Logging.LEVEL_WARNING)
logging = logger.logging()

# INFO filtered out (< WARNING)
logging.info("Initialization complete")  # Not captured

# WARNING and ERROR captured in chronological order
logging.warning("First warning")
logging.error("Second error")
logging.critical("Third critical")

# Retrieve captured messages for assertions
messages = logger.messages()
assert len(messages) == 3
assert "First" in messages[0]
assert "Second" in messages[1]
assert "Third" in messages[2]

# Use case: Test asserts "no errors logged"
logger = LoggerReport(Logging.LEVEL_ERROR)
# ... run code under test ...
assert len(logger.messages()) == 0, "Unexpected errors logged"

# Use case: Verify specific message logged
logger = LoggerReport(Logging.LEVEL_DEBUG)
logging = logger.logging()
# ... code that should log "Database connected" ...
assert any("Database connected" in msg for msg in logger.messages())

Key APIs: LoggerReport(level), .logging(), .messages() → list[str]

Pattern: Report logger captures messages in-memory (vector) for test inspection, unlike Console (stdout) or Null (discards).

Scenario 4: Silent Logging - LoggerNull

When to use: Unit tests (no console spam), performance-critical paths (zero overhead) Test source: test_logging.py:258-270 → TestLoggerNull::test_construction_simple

from dsviper import LoggerNull, Logging

# Create null logger (discards all messages)
logger = LoggerNull()
logging = logger.logging()

# All messages ignored (zero output, zero overhead)
logging.debug("This is not logged")
logging.info("This is not logged")
logging.warning("This is not logged")
logging.error("This is completely ignored")
logging.critical("Even critical messages discarded")

# Level parameter accepted but ignored (Null Object pattern)
logger_with_level = LoggerNull(Logging.LEVEL_ERROR)
logging = logger_with_level.logging()
logging.error("Still ignored")  # Level doesn't matter for Null

# Use case: Test framework default logger
def my_function(logging=LoggerNull().logging()):
    logging.info("Processing...")
    # Function works with any Logging interface (polymorphism)

# Use case: Silent mode flag
import sys
logger = LoggerNull() if "--quiet" in sys.argv else LoggerConsole(Logging.LEVEL_INFO)

Key APIs: LoggerNull(), .logging()

Pattern: Null Object pattern - provides valid Logging interface but does nothing. Enables polymorphism (code accepts Logging, doesn't care about implementation).

Performance: Zero overhead - log() method is empty, compiler optimizes away calls.

Scenario 5: Base64 Encoding

When to use: Encode binary blobs for text-based protocols (JSON, HTTP, XML) Test source: test_base64.py:23-27 → TestBase64Encoding::test_encode_simple

from dsviper import ValueBlob
import base64  # Python stdlib for verification

# Create blob from bytes
blob = ValueBlob(bytes([1, 2, 3, 4]))

# Encode to Base64 string (RFC 4648)
encoded = blob.base64_encode()
assert encoded == "AQIDBA=="

# Verify matches Python stdlib
python_encoded = base64.b64encode(blob.encoded()).decode()
assert encoded == python_encoded

# Empty blob encodes to empty string
empty = ValueBlob(bytes([]))
assert empty.base64_encode() == ""

# Use case: JSON serialization of binary data
import json
data = {
    "image": blob.base64_encode(),  # Binary → text
    "size": blob.size()
}
json_str = json.dumps(data)

Key APIs: ValueBlob.base64_encode() → str

Performance: ~5MB/s encoding throughput (table lookup + bit shifting).

Scenario 6: Base64 Round-Trip (Encode → Decode)

When to use: Verify data preservation, test serialization pipelines Test source: test_base64.py:173-182 → TestBase64Decoding::test_roundtrip

from dsviper import ValueBlob

# Round-trip for various sizes (0, 1, 2, 3, 10, 100, 1000 bytes)
sizes = [0, 1, 2, 3, 10, 100, 1000]

for size in sizes:
    # Create original blob
    original_data = bytes([i % 256 for i in range(size)])
    original_blob = ValueBlob(original_data)

    # Encode to Base64
    encoded = original_blob.base64_encode()

    # Decode back to blob
    decoded_blob = ValueBlob.base64_decode(encoded)

    # Verify data preserved
    assert decoded_blob.encoded() == original_data
    assert decoded_blob == original_blob

# Use case: Receive Base64 from HTTP, decode to blob
http_response_body = "AQIDBA=="  # Base64 from server
blob = ValueBlob.base64_decode(http_response_body)
assert blob.encoded() == bytes([1, 2, 3, 4])

Key APIs: ValueBlob.base64_encode() → str, ValueBlob.base64_decode(str) → ValueBlob

Symmetry: decode(encode(blob)) == blob for all blob sizes (0 to ∞).

Scenario 7: Structured Error Format

When to use: Distributed system debugging, RPC error propagation, machine identification Test source: C++ Viper_Error.cpp:38-60 + doc/Getting_Started_With_Viper.md example

from dsviper import ValueUUId, ViperError

# Trigger error with invalid UUID
try:
    uuid = ValueUUId("invalid-uuid-string")
except ViperError as e:
    # Error format: [processName@hostName]:component:domain:code:message
    print(str(e))
    # Example output:
    # [pid(9443)@mac.home]:Viper.UUId:UUIdErrors:1:The literal 'invalid-uuid-string' is a malformed UUId.

    # Structured fields (C++ side, accessible via str parsing):
    # - hostName: "mac.home" (machine where error occurred)
    # - processName: "pid(9443)" (process ID or custom name)
    # - component: "Viper.UUId" (which Viper component threw error)
    # - domain: "UUIdErrors" (error category)
    # - code: 1 (numeric error code)
    # - message: "The literal 'invalid-uuid-string' is a malformed UUId."

# Error context captured automatically by Error::make()
# - hostname via Socket::hostname() syscall
# - process via getpid() or custom name (Error::setProcessName())

# Use case: RPC error transmission
# Server throws error → serialized to string format → sent via RPC → client parses Error::parse()
# Client now knows: error occurred on "server1.prod", in process "worker-pool-3", component "Database"

Key format: [processName@hostName]:component:domain:code:message

Why structured: 1. Distributed debugging: Identify which machine/process threw error in multi-server deployments 2. RPC serialization: Error::parse(description) deserializes errors from remote processes 3. Component isolation: Know which Viper component failed (UUId, Database, Commit, etc.) 4. Log aggregation: Parse logs to group errors by component/domain/code

Python access: Error details available via str(exception), parsed with regex if needed.

4.2 Integration Patterns

How Utilities combine with other domains:

  1. Database + Error + Logging: python logger = LoggerReport(Logging.LEVEL_ERROR) try: db = Database.open("data.db", logger.logging()) # Database operations use logger for errors except ViperError as e: # Error has context: [process@host]:Database:DatabaseErrors:... assert "Database" in str(e)

  2. Commit System + UUId + NameSpace: python commit_id = ValueUUId.create() # Unique commit identifier namespace = NameSpace(ValueUUId.create(), "MyApp") # Commit uses namespace for qualified concept names

  3. JSON + Base64: python blob = ValueBlob(image_bytes) json_data = { "image": blob.base64_encode(), # Binary in JSON "format": "PNG" } # Later: decode = ValueBlob.base64_decode(json_data["image"])

  4. Type System + Compare + UUId: python uuid1 = ValueUUId.create() uuid2 = ValueUUId.create() result = uuid1.compare(uuid2) # Returns Ordered enum # result: Ordered.ASCENDING, DESCENDING, or SAME

4.3 Test Suite Reference

Full test coverage: python/tests/unit/test_*.py

Test File Lines Tests Coverage
test_base64.py 327 21 Base64 encode/decode, padding cases, large data
test_logging.py 476 16 6 log levels, 3 logger implementations, level filtering
test_value_uuid.py 696 74 UUID generation, parsing, validation, singletons, comparison

Total direct tests: 3 files, 1,499 lines, 111 tests

Indirect usage: Utilities used in 112+ C++ files, tested across all domain test suites (Database tests use Error, Commit tests use UUId, DSM tests use NameSpace, etc.).

5. Technical Constraints

5.1 Performance Characteristics

UUId Operations: - UUId::create(): ~500ns (platform syscall: UuidCreate on Windows, uuid_generate on Unix) - UUId::parse(string): ~200ns (string parsing + validation, 36 characters with hyphens) - UUId::uuidString(): ~150ns (16 bytes → 36-char string conversion) - UUId::operator==(): ~10ns (16-byte memcmp on Windows, UuidEqual on some platforms) - UUId::hash(): ~20ns (combine 16 bytes into std::size_t)

Trade-off: UUID generation requires syscall (not inline-optimizable) but guarantees cryptographic randomness.

Error Operations: - Error::make(): ~1μs (includes getHostname() syscall + string formatting) - Error::parse(): ~500ns (string split + validation) - Exception throw overhead: ~1-5μs (C++ exception unwinding)

Trade-off: Error creation is expensive (~1μs) but only happens on failure path (not hot path).

Logging Operations: - Logging::log() virtual call: ~5ns (vtable dispatch) - Logger::log() level check: ~2ns (integer comparison) - LoggerConsole::print(): ~10μs (stdout syscall) - LoggerReport::print(): ~50ns (vector push_back) - LoggerNull::print(): 0ns (empty method, optimized away)

Trade-off: Virtual call overhead (~5ns) negligible compared to I/O cost (stdout ~10μs).

Base64 Operations: - Base64::encode(): ~5MB/s throughput (table lookup + bit shifting) - Base64::decode(): ~4MB/s throughput (reverse table + validation) - Memory overhead: Output = ceil(input * 4/3) for encoding, input * 3/4 for decoding

Trade-off: Pure algorithm (no syscalls), CPU-bound, single-threaded (no parallelism).

Compare Operations: - compare<T>(a, b): Same cost as a == b + a < b (typically 2-20ns for primitives) - Header-only template: Zero call overhead (inlined by compiler)

NameSpace Operations: - NameSpace::operator==(): ~10ns (delegates to UUId::operator==) - NameSpace::representation(): ~100ns (string concatenation if not global) - NameSpace::Global(): 0ns (returns reference to static instance)

StringHelper Operations (C++ only): - split(): O(n) where n = string length - join(): O(nm) where n = container size, m = average string length - replaceAll(): O(nm) worst case, where n = string length, m = replacements - All operations single-threaded (no parallelism)

TimeHelper Operations: - now(): ~100ns (syscall: std::chrono::high_resolution_clock::now())

Version Operations: - Compile-time macros: 0 runtime cost (values baked into binary)

5.2 Thread Safety

Immutable Types (Thread-Safe):

All operations safe for concurrent read access from multiple threads:

  • UUId - Value semantics, all members const after construction
  • NameSpace - Value semantics, uuid and name members const
  • Error - Exception semantics, all members const (hostName, processName, component, domain, code, message)

Pattern: These types can be safely shared across threads (e.g., passed to thread pool workers) without synchronization.

Mutable Types (NOT Thread-Safe):

Require external synchronization for concurrent access:

  • LoggerReport - Mutable messages vector (appends on log())
  • Problem: Concurrent log() calls corrupt vector (iterator invalidation, data races)
  • Solution: Wrap in mutex or use one LoggerReport per thread

```cpp // ❌ UNSAFE: Multiple threads logging to same LoggerReport LoggerReport logger(Logging::Debug); std::thread t1(& { logger.logging()->info("Thread 1"); }); std::thread t2(& { logger.logging()->info("Thread 2"); });

// ✅ SAFE: Mutex-protected logging std::mutex log_mutex; std::thread t1(& { std::lock_guard lock(log_mutex); logger.logging()->info("Thread 1"); }); ```

  • LoggerConsole - Writes to stdout (shared resource)
  • Problem: Concurrent writes interleave characters (corrupted output)
  • Solution: Application-level stdout mutex (Viper doesn't provide)

Stateless Types (Thread-Safe):

No state, all functions pure:

  • Base64 - Namespace with static functions, no shared state
  • Compare - Template functions, no state
  • StringHelper - Namespace with static functions, no shared state
  • TimeHelper - Namespace with static function, reads system clock (thread-safe syscall)

Singletons (Thread-Safe):

C++11 guarantees thread-safe static initialization:

  • UUId::Invalid() - Returns reference to static instance (initialized once, thread-safe)
  • NameSpace::Global() - Returns static NameSpace instance (thread-safe)

Pattern: First call initializes, subsequent calls return same instance (no locks needed, guaranteed by C++ standard).

5.3 Error Handling

Exception Types:

All Viper utilities throw ViperError (Python) / Error (C++):

  • UUId errors:
  • UUIdErrors::fromLiteral - Invalid UUID string format (code 1)
  • UUIdErrors::create - Platform UUID generation failed (code 2)
  • UUIdErrors::toLiteral - UUID to string conversion failed (code 3)

  • UUIdErrors::equal - UUID comparison syscall failed (code 4)

  • Base64 errors:

  • Base64Errors::decode - Invalid Base64 string (invalid character, wrong padding)

  • Error parsing:

  • Error::parse() returns std::nullopt for malformed error strings (C++), throws in Python if critical

Error Handling Patterns:

  1. Parse with validation: python try: uuid = ValueUUId("user-provided-string") except ViperError as e: print(f"Invalid UUID: {e}")

  2. Factory methods: python uuid = ValueUUId.create() # Never fails (syscall guaranteed to succeed or OS is broken)

  3. Structured error inspection: python try: # ... Viper operation ... except ViperError as e: error_str = str(e) # Parse: [process@host]:component:domain:code:message if ":Viper.UUId:" in error_str: # Handle UUID error specifically elif ":Database:" in error_str: # Handle database error

No Exceptions:

  • UUId::tryParse() (C++ only) - Returns std::optional<UUId> instead of throwing
  • Error::parse() (C++ only) - Returns std::nullopt for malformed strings

Error Context:

All errors include: - Component: Which Viper component threw (e.g., "Viper.UUId", "Database", "Commit") - Domain: Error category (e.g., "UUIdErrors", "DatabaseErrors") - Code: Numeric identifier (domain-specific) - Machine context: Hostname + process name (distributed debugging)

5.4 Memory Model

Value Semantics (Copyable, Comparable):

Types designed for value-based programming:

  • UUId - 16-byte value type (Windows: GUID struct, Unix: uuid_t array)
  • Copyable: UUId copy = original; (shallow copy, 16 bytes)
  • Comparable: uuid1 == uuid2, uuid1 < uuid2 (lexicographic byte order)
  • Hashable: std::hash<UUId> specialized, suitable for std::unordered_map keys

  • Size: 16 bytes (128 bits)

  • NameSpace - UUID + string

  • Copyable: NameSpace copy = original; (UUID copy + string copy)
  • Comparable: Based on UUID equality only (name is display, not identity)
  • Hashable: std::hash based on UUID hash
  • Size: 16 bytes (UUID) + ~24 bytes (std::string overhead) + name length

Exception Semantics (Throw by Value, Catch by Reference):

  • Error - Inherits std::exception, structured fields
  • Throw: throw Error::make("Component", "Domain", 1, "Message"); (value)
  • Catch: catch (Error const & e) { ... } (reference, avoid copy)
  • Size: ~200 bytes (6 std::string members + int64_t)
  • Lifetime: Created on throw, destroyed after catch block

No Heap Allocation:

Types that avoid dynamic memory:

  • Base64 - Stateless namespace, functions operate on caller-provided Blob/string (caller manages memory)
  • Compare - Template function, no allocation
  • TimeHelper - Returns double (8 bytes on stack)

Platform Ownership:

Types that wrap platform resources:

  • UUId - Wraps GUID (Windows) or uuid_t (Unix)
  • Ownership: Value semantics, no manual free (destructor automatic)
  • Platform difference: Windows uses RPC functions (UuidCreate, UuidToStringA), Unix uses <uuid/uuid.h>
  • Byte swapping: Windows GUID byte order ≠ RFC 4122, _swap() normalizes on Windows

Logging Lifetime:

  • Logger implementations - Managed via shared_ptr in Python, raw pointer in C++
  • LoggerReport: Heap-allocated vector for message storage
  • LoggerConsole/LoggerNull: No heap allocation (stateless)
  • Lifetime: Application-managed (create, pass to Viper functions, destroy on app exit)

Static Initialization:

  • UUId::Invalid(): Static instance initialized on first call (C++11 thread-safe)
  • NameSpace::Global(): Static instance initialized on first call
  • Version macros: Preprocessor (no runtime storage)

Reference Semantics:

  • Logging interface: Passed by pointer/reference (Viper functions accept Logging*)
  • Avoids copying logger objects
  • Enables polymorphism (Console, Report, Null implementations)

5.5 Cross-Platform Considerations

UUID Generation:

Platform API Library Byte Order
Windows UuidCreate(&GUID) Rpcrt4.lib GUID byte order (requires _swap())
macOS/Linux uuid_generate(uuid_t) libuuid RFC 4122 (no swap)
FreeBSD uuid_generate(uuid_t) Built-in RFC 4122 (no swap)

Byte swapping:

// Windows GUID byte order ≠ RFC 4122
// First 3 fields (uint32, uint16, uint16) are little-endian in GUID
// RFC 4122 expects big-endian (network byte order)
// _swap() fixes bytes 0-7 (first 3 fields)

String Conversion:

Platform API Format
Windows UuidToStringA(&GUID, &RPC_CSTR) Lowercase "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Unix uuid_unparse_lower(uuid_t, char*) Lowercase (explicit)

Hostname Resolution:

Platform API Header
Windows gethostname(char*, size_t) <winsock2.h>
Unix gethostname(char*, size_t) <unistd.h>

Consistent across platforms (std C++ only):

  • Error: Uses std::string, std::exception (cross-platform)
  • Base64: Pure algorithm, no platform dependencies
  • Logging: std::cout, virtual functions (cross-platform)
  • Compare: Template metaprogramming (header-only)
  • StringHelper/TimeHelper: std::string, std::chrono (cross-platform)

6. Cross-References

Viper Documentation: - doc/Getting_Started_With_Viper.md - Tutorials for UUId generation, NameSpace usage, Error format examples - doc/Internal_Viper.md - NameSpace API in Type System integration (representationIn(), descriptionIn()) - doc/DSM.md - DSM language specification (namespace concept, UUID type literals) - DOMAIN_DOCUMENTATION_STATUS.md - Utilities domain tracking (12/14 domains complete, 86% coverage)

API Documentation: - dsviper_wheel/__init__.pyi - Python type hints for ValueUUId, Logging, LoggerConsole, LoggerReport, LoggerNull, NameSpace

Migration Guides: - doc/Migration_Guide_dsviper_to_Viper.md - Python ↔ C++ translation for UUId, Error, Logging APIs

6.2 Dependencies

This domain USES (Platform APIs only):

Windows Platform: - <guiddef.h> - GUID structure definition - <Rpcrt4.lib> - RPC UUID functions (UuidCreate, UuidToStringA, UuidEqual) - <winsock2.h> - Hostname resolution (gethostname)

Unix/Linux Platform: - <uuid/uuid.h> - UUID generation and parsing (uuid_generate, uuid_parse, uuid_unparse_lower) - <unistd.h> - Hostname resolution (gethostname)

Cross-Platform: - std C++ only - No Boost, no Qt, no external libraries - C++17 minimum (std::optional, std::string, std::exception)

This domain is USED BY (All Viper domains):

Foundation Layer 0: - Type & Value System (src/Viper/Viper_Type*.hpp, src/Viper/Viper_Value*.hpp) - UUId values (TypeUUId, ValueUUId), Compare interface (Ordered), Error handling - Hash System (src/Viper/Viper_Hash*.hpp) - Error handling, StringHelper for hash output - Blob Storage (src/Viper/Viper_Blob*.hpp) - Base64 encoding (ValueBlob API), Error handling

Functional Layer 1: - Stream/Codec (src/Viper/Viper_Stream*.hpp, src/Viper/Viper_Codec*.hpp) - Error handling, StringHelper for enum to string - Database (src/Viper/Viper_Database*.hpp) - Error handling, Logging interface, NameSpace for schema definitions - Commit System (src/Viper/Viper_Commit*.hpp) - UUId for CommitId, Error handling, Logging, NameSpace for concept registration - DSM (src/Viper/Viper_DSM*.hpp) - NameSpace for qualified names (Tuto::Concept), UUId for runtime IDs, StringHelper for parsing, Error handling - RPC/Remote (src/Viper/Viper_RPC*.hpp, src/Viper/Viper_Remote*.hpp) - Error serialization/deserialization (Error::parse()), UUId for packet IDs - Function Pools (src/Viper/Viper_FunctionPool*.hpp) - NameSpace for pool identification, Error handling - Services (src/Viper/Viper_Service*.hpp) - Error handling, Logging, UUId for service identifiers

Utility Layer: - Path System (src/Viper/Viper_Path*.hpp) - Error handling, Compare for path ordering - JSON Support (src/Viper/Viper_Json*.hpp) - Base64 for binary data in JSON, Error handling - HTML (src/Viper/Viper_Html*.hpp) - StringHelper for HTML escaping, representation formatting

Usage statistics: 112+ C++ files across all domains include UUId, Error, NameSpace, or Logging headers.

6.3 Key Type References

C++ Headers (Entry Points):

Header File Purpose Line Count Public Classes/Namespaces
src/Viper/Viper_UUId.hpp RFC 4122 UUID generation 79 UUId (class)
src/Viper/Viper_Error.hpp Structured exception 49 Error (class)
src/Viper/Viper_Logging.hpp Abstract logging interface 39 Logging (abstract class)
src/Viper/Viper_Logger.hpp Template Method base 24 Logger (abstract class)
src/Viper/Viper_LoggerConsole.hpp Console logger ~30 LoggerConsole (class)
src/Viper/Viper_LoggerReport.hpp In-memory logger ~35 LoggerReport (class)
src/Viper/Viper_LoggerNull.hpp Null Object logger ~20 LoggerNull (class)
src/Viper/Viper_NameSpace.hpp Namespace identifier 36 NameSpace (class)
src/Viper/Viper_Base64.hpp Base64 encoding 18 Base64 (namespace)
src/Viper/Viper_Compare.hpp Ternary comparison 21 compare<T> (template)
src/Viper/Viper_StringHelper.hpp String utilities 113 StringHelper (namespace)
src/Viper/Viper_TimeHelper.hpp Time access 13 TimeHelper (namespace)
src/Viper/Viper_Version.hpp Version constants 12 Macros (preprocessor)

Total C++ files: 16 (9 headers + 7 implementations)

Python Bindings:

Binding File Purpose Python API
src/P_Viper/P_Viper_ValueUUId.cpp UUID value type ValueUUId, TypeUUId
src/P_Viper/P_Viper_Error.cpp Exception wrapper ViperError
src/P_Viper/P_Viper_Logging.cpp Logging interface Logging
src/P_Viper/P_Viper_LoggerConsole.cpp Console logger LoggerConsole
src/P_Viper/P_Viper_LoggerReport.cpp Report logger LoggerReport
src/P_Viper/P_Viper_LoggerNull.cpp Null logger LoggerNull
src/P_Viper/P_Viper_NameSpace.cpp Namespace wrapper NameSpace
src/P_Viper/P_ViperRichCompare.hpp Comparison helper Internal (Python __lt__, __eq__)

Total Python bindings: 6 files (8 with headers)

Python Type Hints: - dsviper_wheel/__init__.pyi - Stubs for ValueUUId, ViperError, Logging, LoggerConsole, LoggerReport, LoggerNull, NameSpace

Test Files: - python/tests/unit/test_value_uuid.py (696 lines, 74 tests) - UUID generation, parsing, validation - python/tests/unit/test_logging.py (476 lines, 16 tests) - Logging levels, logger implementations - python/tests/unit/test_base64.py (327 lines, 21 tests) - Base64 encoding/decoding

Document Metadata

Methodology Version: v1.3.1 (Slug-Based Deterministic Naming) Generated Date: 2025-11-15 Last Updated: 2025-11-15 Review Status: ✅ Complete Test Files Analyzed: 3 direct files (test_base64.py, test_logging.py, test_value_uuid.py) Test Coverage: 111 tests across 1,499 lines Golden Examples: 7 scenarios extracted C++ Files: 16 (9 headers + 7 implementations) Python Bindings: 6 files Components: 9 (UUId, Error, Logging, Logger, 3 Logger implementations, NameSpace, Base64, Compare, StringHelper, TimeHelper, Version) Sub-domains: 6 (Core Identity, Logging System, Error Handling, Encoding, Comparison, String/Time Helpers)

Changelog: - v1.3.1 (2025-11-15): Initial documentation following /document-domain v1.3.1 methodology - Phase 0.5 audit: 9 components identified (3 direct test files, 112+ indirect usage files) - Phase 0.75 C++ analysis: 9 design patterns identified (Singleton, Factory, Strategy, Template Method, Null Object, Stateless Namespace, Adapter, Value Semantics, Structured Exception) - Phase 1 golden scenarios: 7 extracted from tests (UUId generation/parsing, 3 logger types, Base64 encode/decode, Error format) - Phase 5 implementation: 6 sections completed (Purpose, Overview, Decomposition, Usage, Technical, References) - Enumeration Matrix: 9 components verified (7 with Python bindings, 2 C++ internal) - Cross-platform analysis: Windows GUID vs Unix uuid_t byte swapping documented - Special emphasis: Foundation Layer 0 (zero Viper dependencies, used by all 112+ files)

Regeneration Trigger: - When /document-domain reaches v2.0 (methodology changes requiring full regeneration) - When Utilities C++ API changes significantly (major version bump, breaking changes) - When new utility components added (e.g., new logger types, new encoding formats) - When cross-platform behavior changes (Windows/Unix API updates)

Appendix: Domain Statistics

C++ Files: 16 total - Headers: 9 (UUId, Error, Logging, Logger, LoggerConsole, LoggerReport, LoggerNull, NameSpace, Base64, Compare, StringHelper, TimeHelper, Version) - Implementations: 7 (UUId, Error, Logging, Logger, LoggerConsole, LoggerReport, LoggerNull, NameSpace, Base64, StringHelper, TimeHelper)

Python Bindings: 6 files (UUId, Error, Logging, LoggerConsole, LoggerReport, LoggerNull, NameSpace)

Test Files: 3 direct (test_base64.py, test_logging.py, test_value_uuid.py)

Test Methods: 111 total (21 Base64 + 16 Logging + 74 UUId)

Sub-domains: 6 1. Core Identity (UUId, NameSpace, Version) 2. Logging System (Logging, Logger, 3 implementations) 3. Error Handling (Error) 4. Encoding (Base64) 5. Comparison (Compare) 6. String/Time Helpers (StringHelper, TimeHelper)

Design Patterns: 9 1. Singleton (UUId::Invalid, NameSpace::Global) 2. Factory (UUId::create, Error::make) 3. Strategy (Logging interface with 3 backends) 4. Template Method (Logger with level filtering) 5. Null Object (LoggerNull) 6. Stateless Namespace (Base64, StringHelper, TimeHelper) 7. Adapter (UUId wraps Windows GUID / Unix uuid_t) 8. Value Semantics (UUId, NameSpace copyable/comparable/hashable) 9. Structured Exception (Error with parseable format)

External Dependencies: Platform APIs only (Windows: Rpcrt4.lib, Unix: libuuid)

Usage: 112+ C++ files include Utilities headers (universally used across all Viper domains)

Document Version: 1.3.1 Tracking: DOMAIN_DOCUMENTATION_STATUS.md, .claude/domains_registry.json Next Update: When new utility components added or methodology upgrades to v2.0

Generated following /document-domain v1.3.1 methodology (Slug-Based Deterministic Naming) - Test-driven examples, C++ architecture analysis, cross-platform documentation, progressive validation.