feat(diagnostics): add process environment overrides

Author: robertvokac

CLAUDE.md

@@ -9,7 +9,7 @@
 ## Non-negotiable rules
 
 1. **Zero errors, zero warnings** before any commit. `cmake --build build --parallel 4` must be clean.
-2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,675 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
+2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,678 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
 3. **Push only to `feature/work`.** Never push to `develop` or `master`, and never create tags, without explicit per-action user approval.
 4. **SPDX header on every project source/header** — `// SPDX-License-Identifier: MIT` + copyright + .NET attribution. Vendored sources retain their upstream headers; Markdown uses an HTML SPDX comment where one is present.
 5. **Property naming:** always `getXxxProperty()` / `setXxxProperty()`. Exception: indexers

NEXT.md

@@ -4,9 +4,9 @@
 # NEXT.md
 
 *Last verified: 2026-07-25. Branch: `feature/work`. The P0 component-boundary
-repair, three P1 parity repairs, P1 portability revalidation, and twenty bounded
+repair, three P1 parity repairs, P1 portability revalidation, and twenty-one bounded
 P2 API slices are complete: 41 physical modules, 90 production dependency
-edges, and 12,675 tests across 37 executables.*
+edges, and 12,678 tests across 37 executables.*
 
 This is the cold-start handoff for the next working session. Keep it focused
 on verified facts, remaining bounded work, and commands needed to resume.
@@ -28,7 +28,7 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - The ten-job selective consumer matrix, including a direct
   `Collections.Blocking` consumer, is green. Text.Json retains its target
   absence and negative include-leakage assertions.
-- The full native baseline is a warning-free build with 12,675 passing tests
+- The full native baseline is a warning-free build with 12,678 passing tests
   across 36 component executables and one integration executable.
 - `TaskT<TResult>::ContinueWith` now supports both action and result-producing
   callbacks. It runs inline on completion; `NotOn*` and `OnlyOn*` filter the
@@ -80,6 +80,9 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - `Trace::WriteIf` and `Trace::WriteLineIf` now conditionally preserve the
   existing stderr write/newline behavior; category and listener surfaces stay
   intentionally deferred.
+- `ProcessStartInfo` now supplies explicit child-only environment overrides;
+  unspecified values inherit, empty values remain empty, and invalid variable
+  names are rejected before forking.
 - MinGW-w64 GCC 14-win32/CMake 3.31.6 and Emscripten 5.0.7/CMake 3.31.6 both
   compile the post-modular `All` graph and selective `Text.Json` libraries.
   This is compile-only evidence: cross tests were deliberately disabled.
@@ -88,7 +91,7 @@ Historical session detail belongs in git history and `plan.sqlite3`.
   ASan/LSan ownership scenarios, including 100 continuation teardowns, pass.
 
 The local `plan.sqlite3` snapshot contains 16,201 classified `task` rows and
-1,762 completed tickets. Ticket #1737 records the completed P0 split, tickets
+1,763 completed tickets. Ticket #1737 records the completed P0 split, tickets
 #1738/#1739 the MemoryStream and generic-continuation repairs, ticket #1740 the
 XML whitespace repair, #1741 the completed cross-build revalidation and
 `WebProxy` portability fix, #1742 focused sanitizer evidence, and #1743 the
@@ -103,7 +106,8 @@ queries, #1755 for its comparer-aware binary search, #1756 for its default
 range sort, #1757 for `BigInteger` bitwise operators, #1758 for signed
 `BigInteger` shifts, #1759 for byte-vector conversion, and #1760 for the
 `ImmutableList<T>` Builder core, #1761 for RFC 2152 UTF-7, and #1762 for
-conditional Trace writes; it is git-ignored and is not part of a fresh clone.
+conditional Trace writes, and #1763 for ProcessStartInfo environment overrides;
+it is git-ignored and is not part of a fresh clone.
 
 ## P0 completion: restore Collections isolation
 

README.md

@@ -7,7 +7,7 @@ collector, or the complete .NET platform.
 
 The repository currently builds as 41 independently selectable CMake
 components. The verified Linux baseline on 2026-07-25 is a warning-free build
-with **12,675 passing tests across 37 test executables**.
+with **12,678 passing tests across 37 test executables**.
 
 ## What is included
 
@@ -181,7 +181,7 @@ Other platform evidence is narrower:
 
 | Platform/toolchain | Verified scope |
 |---|---|
-| Linux/GCC | Current full component build and all 12,675 tests. |
+| Linux/GCC | Current full component build and all 12,678 tests. |
 | Windows/MinGW | MinGW-w64 GCC 14-win32/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. GoogleTest was not cross-built and repository CI remains Ubuntu-only. |
 | Emscripten | Emscripten 5.0.7/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. Tests were not cross-built or run, and some runtime APIs deliberately throw `PlatformNotSupportedException`. |
 | macOS/Apple Clang | Real downstream Xcode 15.4 builds drove portability fixes on 2026-07-20; this repository has no macOS job or recorded full standalone test baseline. |

docs/CMakeComponents.md

@@ -131,7 +131,7 @@ are named `SharpRuntimeTests_<Component>`; genuinely cross-module scenarios
 are in `SharpRuntimeIntegrationTests`. CTest also discovers every individual
 GoogleTest case.
 
-The verified 2026-07-25 `All` baseline contains 12,675 tests across 36
+The verified 2026-07-25 `All` baseline contains 12,678 tests across 36
 component executables and one integration executable.
 
 ## Boundary validation and CI

modules/diagnostics/include/System/Diagnostics/ProcessStartInfo.hpp

@@ -3,6 +3,7 @@
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #pragma once
 
+#include <map>
 #include <string>
 #include <vector>
 
@@ -23,16 +24,17 @@ namespace System::Diagnostics {
      * Windows; on POSIX, argv is always a plain string array with no re-quoting step at all) --
      * use @ref getArgumentListProperty directly for anything containing spaces or quotes.
      *
-     * @note Status: Partial. UseShellExecute, redirected standard input, environment-variable
-     * overrides, and window-style/verb properties (all Windows-shell-specific or otherwise out of
-     * scope for a POSIX-only game-runtime launcher) are not implemented -- see
+     * @note Status: Partial. UseShellExecute, redirected standard input, environment enumeration
+     * and removal semantics, and window-style/verb properties (all Windows-shell-specific or
+     * otherwise out of scope for a POSIX-only game-runtime launcher) are not implemented -- see
      * System::Diagnostics::Process's class doc-comment for the full list of deliberately deferred
      * surface.
      */
     class ProcessStartInfo {
         std::string fileName_;
         std::string arguments_;
         std::vector<std::string> argumentList_;
+        std::map<std::string, std::string> environmentVariables_;
         std::string workingDirectory_;
         bool redirectStandardOutput_ = false;
         bool redirectStandardError_ = false;
@@ -63,6 +65,20 @@ namespace System::Diagnostics {
         [[nodiscard]] std::vector<std::string>& getArgumentListProperty() { return argumentList_; }
         [[nodiscard]] const std::vector<std::string>& getArgumentListProperty() const { return argumentList_; }
 
+        /**
+         * @brief Gets explicitly supplied child environment-variable overrides.
+         *
+         * Entries are applied only to the launched child; unspecified variables are inherited
+         * from the parent. Variable names must be nonempty and must not contain '=' when Start()
+         * is called. An empty value is passed to the child as an empty variable value.
+         */
+        [[nodiscard]] std::map<std::string, std::string>& getEnvironmentVariablesProperty() {
+            return environmentVariables_;
+        }
+        [[nodiscard]] const std::map<std::string, std::string>& getEnvironmentVariablesProperty() const {
+            return environmentVariables_;
+        }
+
         /** @brief Gets or sets the working directory for the process. Empty means inherit the caller's current directory. */
         [[nodiscard]] const std::string& getWorkingDirectoryProperty() const { return workingDirectory_; }
         void setWorkingDirectoryProperty(const std::string& value) { workingDirectory_ = value; }

modules/diagnostics/src/System/Diagnostics/Process.cpp

@@ -2,6 +2,7 @@
 // Copyright (c) Robert Vokac and contributors
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #include "System/Diagnostics/Process.hpp"
+#include "System/ArgumentException.hpp"
 #include "System/InvalidOperationException.hpp"
 #include "System/PlatformNotSupportedException.hpp"
 
@@ -134,6 +135,13 @@ bool Process::Start() {
     const ProcessStartInfo& si = impl_->startInfo;
     if (si.getFileNameProperty().empty())
         throw System::InvalidOperationException("Cannot start process because a file name has not been provided.");
+    for (const auto& [name, value] : si.getEnvironmentVariablesProperty()) {
+        (void)value;
+        if (name.empty() || name.find('=') != std::string::npos) {
+            throw System::ArgumentException(
+                "Environment variable names must be nonempty and cannot contain '='.", "name");
+        }
+    }
 
     // Build argv: argv[0] is conventionally the program name, followed by ArgumentList (the
     // unambiguous path -- no shell/OS quoting), then a naive whitespace split of Arguments for
@@ -181,6 +189,9 @@ bool Process::Start() {
         if (!si.getWorkingDirectoryProperty().empty()) {
             if (::chdir(si.getWorkingDirectoryProperty().c_str()) != 0) ::_exit(127);
         }
+        for (const auto& [name, value] : si.getEnvironmentVariablesProperty()) {
+            if (::setenv(name.c_str(), value.c_str(), 1) != 0) ::_exit(127);
+        }
         ::execvp(argv[0], argv.data());
         ::_exit(127); // execvp only returns on failure
     }

modules/diagnostics/tests/System/Diagnostics/ProcessEnvironmentOverrideTests.cpp

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) Robert Vokac and contributors
+// Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
+#include <gtest/gtest.h>
+
+#include <cstdlib>
+#include <string>
+
+#include "System/ArgumentException.hpp"
+#include "System/Diagnostics/Process.hpp"
+
+using System::Diagnostics::Process;
+using System::Diagnostics::ProcessStartInfo;
+
+namespace {
+constexpr const char* EnvironmentKey = "SHARP_RUNTIME_PROCESS_ENV_TEST_1763";
+}
+
+TEST(ProcessEnvironmentOverrideTest, ChildReceivesOverrideWithoutChangingParentEnvironment) {
+    const char* before = std::getenv(EnvironmentKey);
+    const std::string beforeValue = before == nullptr ? "" : before;
+    const bool hadBeforeValue = before != nullptr;
+
+    ProcessStartInfo startInfo("/bin/sh");
+    startInfo.getArgumentListProperty().push_back("-c");
+    startInfo.getArgumentListProperty().push_back("printf '%s' \"$SHARP_RUNTIME_PROCESS_ENV_TEST_1763\"");
+    startInfo.getEnvironmentVariablesProperty()[EnvironmentKey] = "child-value";
+    startInfo.setRedirectStandardOutputProperty(true);
+    Process process = Process::Start(startInfo);
+    process.WaitForExit();
+
+    EXPECT_EQ(process.getExitCodeProperty(), 0);
+    EXPECT_EQ(process.getStandardOutputTextProperty(), "child-value");
+    const char* after = std::getenv(EnvironmentKey);
+    EXPECT_EQ(after != nullptr, hadBeforeValue);
+    if (after != nullptr) {
+        EXPECT_EQ(std::string(after), beforeValue);
+    }
+}
+
+TEST(ProcessEnvironmentOverrideTest, EmptyValueIsPassedLiterallyToChild) {
+    ProcessStartInfo startInfo("/bin/sh");
+    startInfo.getArgumentListProperty().push_back("-c");
+    startInfo.getArgumentListProperty().push_back("test -z \"$SHARP_RUNTIME_PROCESS_ENV_TEST_1763\"");
+    startInfo.getEnvironmentVariablesProperty()[EnvironmentKey] = "";
+    Process process = Process::Start(startInfo);
+    process.WaitForExit();
+
+    EXPECT_EQ(process.getExitCodeProperty(), 0);
+}
+
+TEST(ProcessEnvironmentOverrideTest, InvalidVariableNamesAreRejectedBeforeForking) {
+    ProcessStartInfo startInfo("/bin/true");
+    startInfo.getEnvironmentVariablesProperty()["INVALID=NAME"] = "value";
+
+    EXPECT_THROW(Process::Start(startInfo), System::ArgumentException);
+}

plan.md

@@ -1,7 +1,7 @@
 # Sharp Runtime plan
 
 *Last verified: 2026-07-25 — 41 physical components, 90 direct production
-dependency edges, a clean native build, 12,675 passing tests across 37
+dependency edges, a clean native build, 12,678 passing tests across 37
 executables, and a green ten-job selective matrix.*
 
 Sharp Runtime is in a consumer-driven expansion phase. The original type
@@ -32,7 +32,7 @@ was never created. Neither file should be linked as current documentation.
 ### Code and validation
 
 - Native Linux/GCC build: zero errors and zero warnings.
-- Tests: 12,675 passing across 36 component binaries plus one integration
+- Tests: 12,678 passing across 36 component binaries plus one integration
   binary.
 - Component graph: 41 physical modules and 90 direct production edges.
 - Boundary validator: no cycles, duplicate public include paths, orphan
@@ -52,7 +52,7 @@ The 2026-07-25 local snapshot contains:
 | Table | State |
 |---|---|
 | `task` | 16,201 rows: 1,082 `ported`, 140 `ignore`, 14,979 legacy `ignored`; no unclassified or `tobedecided` rows |
-| `ticket` | 1,762 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
+| `ticket` | 1,763 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
 
 Because `plan.sqlite3` is git-ignored, these counts describe the maintainer
 snapshot, not data shipped in a fresh clone.
@@ -151,6 +151,9 @@ assertion without an explicit architecture decision.
 - Added conditional `Trace::WriteIf` and `Trace::WriteLineIf` under ticket
   #1762. They suppress output when false and retain the existing stderr
   write/newline behavior when true.
+- Added explicit ProcessStartInfo child environment overrides under ticket
+  #1763. They are validated before fork, passed only to the child, and retain
+  inherited values not explicitly overridden.
 - Added consumer-driven coverage across core, collections, IO, networking,
   threading/tasks, text/JSON, XML, numerics, globalization, and cryptographic
   hashing/random APIs.
@@ -211,7 +214,7 @@ The first consumer-driven ports after modularization added:
 - XML schema exception types.
 
 The verified test baseline grew from 12,494 at the modularization checkpoint
-to 12,675.
+to 12,678.
 
 ## Candidate roadmap