System Domain API Guidelines

Core Semantics

user or group id = platform identity identifier such as a POSIX UID/GID or Windows SID string
user or group name = display name resolved from a platform identity identifier, with optional domain
environment variable = process-wide native name/value entry
process id = opaque potentially valid identifier that need not identify an existing process
process identity = process id plus valid start time when identifier reuse matters
subprocess = one directly launched operating-system child, never a shell command

Primary Types

UserId, GroupId // type-safe platform identity identifiers
UserName, GroupName // type-safe platform identity names
UserLookup // cached lookup service for platform user and group identities
EnvironmentVariables // portable access to process environment variables
ProcessId // opaque process identifier created only by system APIs
ProcessInfo // eager portable process snapshot
Subprocess // move-only owner and controller for one child process
SubprocessOptions // launch environment, working directory, and stream policies
SubprocessExitStatus // exit code or POSIX termination signal

Secondary Types

PlatformError // native operating-system failure
PlatformErrorContext // portable structured native failure context
PlatformErrorCategory // native subsystem or API failure category
OperatingSystem, CpuArchitecture // comparable smart-enum host classifications
SubprocessOutputMode // inherit, discard, or bounded capture

Lookup Patterns

o.userNameForId(id) -> UserName // resolve a platform user identifier to a display name
o.groupNameForId(id) -> GroupName // resolve a platform group identifier to a display name
o.userIdForName(name) -> UserId // resolve a platform user name to an identifier
o.groupIdForName(name) -> GroupId // resolve a platform group name to an identifier
o.clearCache() // clear cached identity lookups

Environment Variable Patterns

o.get(name) -> optional<String> // read while preserving missing versus empty
o.get(name, defaultValue) -> String // read with an explicit fallback
o.getOrThrow(name) -> String // read or throw if missing or inaccessible
o.set(name, value) -> bool // set without throwing
o.setOrThrow(name, value) // set or throw on failure
o.remove(name) -> bool // idempotently remove without throwing
o.removeOrThrow(name) // idempotently remove or throw on failure

Process Information Patterns

T() // eagerly load the current-process snapshot
T(processId) // eagerly load the process currently using the identifier
o.processId()/exists() -> T // inspect the followed identifier and cached existence
o.executablePath/parentProcessId/startTime/ownerId() -> T // inspect cached values or invalid sentinels
o.❮attribute❯OrThrow() -> T // inspect a cached value or rethrow its cached native diagnostic
o.reload() // atomically replace the snapshot without throwing
o.reloadOrThrow() // atomically replace the snapshot and report an unexpected lookup failure

System Information Patterns

operatingSystem() -> OperatingSystem // classify the current host in system::info
cpuArchitecture() -> CpuArchitecture // classify the native host architecture in system::info
logicalCpuCount() -> uint32_t // get a usable thread-count hint of at least one in system::info

Subprocess Patterns

T::start(executable, arguments, options) -> Subprocess // launch an owned direct child
T::startDetached(executable, arguments, options) // launch without process control or capture
o.processId() -> ProcessId // inspect the launched identifier, including after exit
o.isRunning() -> bool // poll native child state
o.exitStatus() -> optional<SubprocessExitStatus> // inspect cached terminal state
o.wait() -> SubprocessExitStatus // wait indefinitely and reap
o.wait(timeout) -> optional<SubprocessExitStatus> // wait until a deadline and reap on exit
o.terminate()/kill() // request regular or forceful native termination
o.standardOutput()/standardError() -> String // read a retained captured prefix
o.was❮Stream❯Truncated() -> bool // detect output beyond the capture limit
o.setEnvironmentVariable(name, value) // assign after optional inheritance
o.removeEnvironmentVariable(name) // remove after optional inheritance

Application Patterns

application().userLookup() -> UserLookup& // access the application-shared lookup service

Platform Error Patterns

T(operation[, nativeCode]) // create native failure context for an operation
o.category()/nativeCode()/nativeMessage() -> T // inspect structured native failure data
o.set❮Property❯(value) -> PlatformErrorContext& // fluently add portable diagnostic context