feat(numerics): add big integer bitwise operators

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,650 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,654 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 fourteen bounded
+repair, three P1 parity repairs, P1 portability revalidation, and fifteen bounded
 P2 API slices are complete: 41 physical modules, 90 production dependency
-edges, and 12,650 tests across 37 executables.*
+edges, and 12,654 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,650 passing tests
+- The full native baseline is a warning-free build with 12,654 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
@@ -65,6 +65,9 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - `ImmutableList<T>::Sort(index, count)` sorts only a valid requested range
   with the default comparison. Zero-length boundary ranges are valid and the
   source plus outside elements remain unchanged.
+- `BigInteger` supports `&, |, ^, ~` and their compound assignments using
+  infinite two's-complement semantics, including negative and beyond-native
+  integer values. Shift and byte-array conversion APIs remain deferred.
 - 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.
@@ -73,7 +76,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,756 completed tickets. Ticket #1737 records the completed P0 split, tickets
+1,757 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
@@ -84,8 +87,9 @@ UTF-8 `BinaryReader` batch-character APIs, #1749 `ImmutableList<T>` copying,
 and #1750 its custom comparison sort, and #1751 its range reverse. The
 database also records #1752 for its `IComparer<T>` sorting overloads, #1753
 for its equality-based item mutations, #1754 for its equality-based range
-queries, #1755 for its comparer-aware binary search, and #1756 for its default
-range sort; it is git-ignored and is not part of a fresh clone.
+queries, #1755 for its comparer-aware binary search, #1756 for its default
+range sort, and #1757 for `BigInteger` bitwise operators; it is git-ignored
+and is not part of a fresh clone.
 
 ## P0 completion: restore Collections isolation
 
@@ -231,8 +235,8 @@ slice, create a ticket, and keep the changes isolated:
 1. **`ImmutableList<T>` builder support.** Treat `ToBuilder`/`Builder` as a
    separately scoped API design, not an opportunistic extension of the
    vector-backed immutable-list methods.
-2. **Other documented partial surfaces.** Examples include `BigInteger`
-   bitwise operations, fuller UTF-7 behavior, and wider debugger/process/XML
+2. **Other documented partial surfaces.** Examples include `BigInteger` shift
+   or byte-array APIs, fuller UTF-7 behavior, and wider debugger/process/XML
    surfaces.
 3. **Doxygen warning baseline.** Establish a reproducible warning count, then
    keep touched public APIs from increasing it; do not do a mass comment-only

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,650 passing tests across 37 test executables**.
+with **12,654 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,650 tests. |
+| Linux/GCC | Current full component build and all 12,654 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,650 tests across 36
+The verified 2026-07-25 `All` baseline contains 12,654 tests across 36
 component executables and one integration executable.
 
 ## Boundary validation and CI

modules/numerics/include/System/Numerics/BigInteger.hpp

@@ -20,9 +20,9 @@ namespace System::Numerics {
      *
      * Partial C++ counterpart of .NET System.Numerics.BigInteger.
      *
-     * @note Status: Full arithmetic — add, subtract, multiply, divide, modulo,
-     *   comparisons, ToString, Parse, TryParse all implemented.
-     *   Bitwise operations are not implemented.
+     * @note Status: Arithmetic, comparisons, formatting/parsing, and bitwise
+     *   operators are implemented. Shift and byte-array conversion APIs remain
+     *   outside this focused port.
      */
     class BigInteger {
         bool                  negative_ = false;
@@ -52,6 +52,11 @@ namespace System::Numerics {
                divmodMag(std::vector<uint32_t> a, std::vector<uint32_t> b);
 
         static std::vector<uint32_t> fromUInt64(uint64_t v);
+        static std::vector<uint16_t> magnitudeToBinary16(const std::vector<uint32_t>& magnitude);
+        static std::vector<uint32_t> binary16ToMagnitude(const std::vector<uint16_t>& words);
+        static std::vector<uint16_t> toTwosComplement16(const BigInteger& value, size_t wordCount);
+        static BigInteger fromTwosComplement16(std::vector<uint16_t> words);
+        [[nodiscard]] BigInteger bitwise(const BigInteger& other, char operation) const;
 
     public:
         // ------------------------------------------------------------------
@@ -129,11 +134,23 @@ namespace System::Numerics {
          */
         BigInteger operator%(const BigInteger& o) const;
 
+        /** @brief Returns the bitwise AND using infinite two's-complement semantics. */
+        BigInteger operator&(const BigInteger& o) const;
+        /** @brief Returns the bitwise OR using infinite two's-complement semantics. */
+        BigInteger operator|(const BigInteger& o) const;
+        /** @brief Returns the bitwise XOR using infinite two's-complement semantics. */
+        BigInteger operator^(const BigInteger& o) const;
+        /** @brief Returns the bitwise complement using infinite two's-complement semantics. */
+        BigInteger operator~() const;
+
         BigInteger& operator+=(const BigInteger& o);
         BigInteger& operator-=(const BigInteger& o);
         BigInteger& operator*=(const BigInteger& o);
         BigInteger& operator/=(const BigInteger& o);
         BigInteger& operator%=(const BigInteger& o);
+        BigInteger& operator&=(const BigInteger& o);
+        BigInteger& operator|=(const BigInteger& o);
+        BigInteger& operator^=(const BigInteger& o);
 
         // ------------------------------------------------------------------
         // Comparison operators

modules/numerics/src/System/Numerics/BigInteger.cpp

@@ -175,6 +175,93 @@ std::vector<uint32_t> BigInteger::fromUInt64(uint64_t v) {
     return r;
 }
 
+std::vector<uint16_t> BigInteger::magnitudeToBinary16(const std::vector<uint32_t>& magnitude) {
+    std::vector<uint32_t> remaining = magnitude;
+    std::vector<uint16_t> words;
+    while (!(remaining.size() == 1 && remaining[0] == 0)) {
+        uint32_t remainder = 0;
+        remaining = divMagByLimb(remaining, 65536u, remainder);
+        words.push_back(static_cast<uint16_t>(remainder));
+    }
+    if (words.empty()) {
+        words.push_back(0);
+    }
+    return words;
+}
+
+std::vector<uint32_t> BigInteger::binary16ToMagnitude(const std::vector<uint16_t>& words) {
+    std::vector<uint32_t> magnitude = {0};
+    for (auto it = words.rbegin(); it != words.rend(); ++it) {
+        magnitude = mulMag(magnitude, {65536u});
+        if (*it != 0) {
+            magnitude = addMag(magnitude, {static_cast<uint32_t>(*it)});
+        }
+    }
+    return magnitude;
+}
+
+std::vector<uint16_t> BigInteger::toTwosComplement16(const BigInteger& value, size_t wordCount) {
+    std::vector<uint16_t> words = magnitudeToBinary16(value.mag_);
+    words.resize(wordCount, 0);
+    if (!value.negative_) {
+        return words;
+    }
+
+    for (auto& word : words) {
+        word = static_cast<uint16_t>(~word);
+    }
+    uint32_t carry = 1;
+    for (auto& word : words) {
+        const uint32_t sum = static_cast<uint32_t>(word) + carry;
+        word = static_cast<uint16_t>(sum);
+        carry = sum >> 16;
+        if (carry == 0) {
+            break;
+        }
+    }
+    return words;
+}
+
+BigInteger BigInteger::fromTwosComplement16(std::vector<uint16_t> words) {
+    const bool negative = (words.back() & 0x8000u) != 0;
+    if (negative) {
+        for (auto& word : words) {
+            word = static_cast<uint16_t>(~word);
+        }
+        uint32_t carry = 1;
+        for (auto& word : words) {
+            const uint32_t sum = static_cast<uint32_t>(word) + carry;
+            word = static_cast<uint16_t>(sum);
+            carry = sum >> 16;
+            if (carry == 0) {
+                break;
+            }
+        }
+    }
+
+    BigInteger result;
+    result.mag_ = binary16ToMagnitude(words);
+    result.negative_ = negative;
+    result.trim();
+    return result;
+}
+
+BigInteger BigInteger::bitwise(const BigInteger& other, char operation) const {
+    const size_t wordCount = std::max(magnitudeToBinary16(mag_).size(),
+                                      magnitudeToBinary16(other.mag_).size()) + 1;
+    const std::vector<uint16_t> left = toTwosComplement16(*this, wordCount);
+    const std::vector<uint16_t> right = toTwosComplement16(other, wordCount);
+    std::vector<uint16_t> result(wordCount);
+    for (size_t index = 0; index < wordCount; ++index) {
+        switch (operation) {
+        case '&': result[index] = static_cast<uint16_t>(left[index] & right[index]); break;
+        case '|': result[index] = static_cast<uint16_t>(left[index] | right[index]); break;
+        default:  result[index] = static_cast<uint16_t>(left[index] ^ right[index]); break;
+        }
+    }
+    return fromTwosComplement16(std::move(result));
+}
+
 // ---------------------------------------------------------------------------
 // Constructors
 // ---------------------------------------------------------------------------
@@ -338,11 +425,27 @@ BigInteger BigInteger::operator%(const BigInteger& o) const {
     return r;
 }
 
+BigInteger BigInteger::operator&(const BigInteger& o) const { return bitwise(o, '&'); }
+BigInteger BigInteger::operator|(const BigInteger& o) const { return bitwise(o, '|'); }
+BigInteger BigInteger::operator^(const BigInteger& o) const { return bitwise(o, '^'); }
+
+BigInteger BigInteger::operator~() const {
+    const size_t wordCount = magnitudeToBinary16(mag_).size() + 1;
+    std::vector<uint16_t> words = toTwosComplement16(*this, wordCount);
+    for (auto& word : words) {
+        word = static_cast<uint16_t>(~word);
+    }
+    return fromTwosComplement16(std::move(words));
+}
+
 BigInteger& BigInteger::operator+=(const BigInteger& o) { *this = *this + o; return *this; }
 BigInteger& BigInteger::operator-=(const BigInteger& o) { *this = *this - o; return *this; }
 BigInteger& BigInteger::operator*=(const BigInteger& o) { *this = *this * o; return *this; }
 BigInteger& BigInteger::operator/=(const BigInteger& o) { *this = *this / o; return *this; }
 BigInteger& BigInteger::operator%=(const BigInteger& o) { *this = *this % o; return *this; }
+BigInteger& BigInteger::operator&=(const BigInteger& o) { *this = *this & o; return *this; }
+BigInteger& BigInteger::operator|=(const BigInteger& o) { *this = *this | o; return *this; }
+BigInteger& BigInteger::operator^=(const BigInteger& o) { *this = *this ^ o; return *this; }
 
 // ---------------------------------------------------------------------------
 // Comparison

modules/numerics/tests/System/Numerics/BigIntegerBitwiseTests.cpp

@@ -0,0 +1,56 @@
+// 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 "System/Numerics/BigInteger.hpp"
+
+using System::Numerics::BigInteger;
+
+TEST(BigIntegerBitwiseTest, PositiveOperandsProduceExpectedValues) {
+    const BigInteger left(5);
+    const BigInteger right(3);
+
+    EXPECT_EQ((left & right).ToString(), "1");
+    EXPECT_EQ((left | right).ToString(), "7");
+    EXPECT_EQ((left ^ right).ToString(), "6");
+    EXPECT_EQ((~left).ToString(), "-6");
+}
+
+TEST(BigIntegerBitwiseTest, NegativeOperandsUseTwosComplementSemantics) {
+    const BigInteger negativeFive(-5);
+    const BigInteger three(3);
+
+    EXPECT_EQ((negativeFive & three).ToString(), "3");
+    EXPECT_EQ((negativeFive | three).ToString(), "-5");
+    EXPECT_EQ((negativeFive ^ three).ToString(), "-8");
+    EXPECT_EQ((~negativeFive).ToString(), "4");
+}
+
+TEST(BigIntegerBitwiseTest, NegativePairsAndZeroRetainInfiniteSignExtension) {
+    const BigInteger negativeFive(-5);
+    const BigInteger negativeThree(-3);
+
+    EXPECT_EQ((negativeFive & negativeThree).ToString(), "-7");
+    EXPECT_EQ((negativeFive | negativeThree).ToString(), "-1");
+    EXPECT_EQ((negativeFive ^ negativeThree).ToString(), "6");
+    EXPECT_EQ((BigInteger::Zero & negativeFive).ToString(), "0");
+    EXPECT_EQ((BigInteger::Zero | negativeFive).ToString(), "-5");
+    EXPECT_EQ((~BigInteger::Zero).ToString(), "-1");
+}
+
+TEST(BigIntegerBitwiseTest, OperatesBeyondNativeIntegerWidthAndSupportsAssignments) {
+    const BigInteger highBit = BigInteger::Parse("18446744073709551616");
+    const BigInteger lowBits = BigInteger::Parse("4294967295");
+
+    EXPECT_EQ((highBit & lowBits).ToString(), "0");
+    EXPECT_EQ((highBit | lowBits).ToString(), "18446744078004518911");
+    EXPECT_EQ((highBit ^ lowBits).ToString(), "18446744078004518911");
+
+    BigInteger assigned = highBit;
+    assigned |= lowBits;
+    EXPECT_EQ(assigned.ToString(), "18446744078004518911");
+    assigned &= highBit;
+    EXPECT_EQ(assigned.ToString(), "18446744073709551616");
+    assigned ^= highBit;
+    EXPECT_EQ(assigned.ToString(), "0");
+}

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,650 passing tests across 37
+dependency edges, a clean native build, 12,654 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,650 passing across 36 component binaries plus one integration
+- Tests: 12,654 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,756 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
+| `ticket` | 1,757 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.
@@ -130,6 +130,10 @@ assertion without an explicit architecture decision.
 - Added default-comparison `ImmutableList<T>::Sort(index, count)` under
   ticket #1756. It sorts only a valid range, preserves the source and outside
   elements, and accepts zero-length boundary ranges.
+- Added `BigInteger` bitwise AND, OR, XOR, complement, and compound assignment
+  operators under ticket #1757. The base-10^9 backing converts internally to
+  a sign-extended two's-complement form so negative and large operands retain
+  .NET semantics.
 - Added consumer-driven coverage across core, collections, IO, networking,
   threading/tasks, text/JSON, XML, numerics, globalization, and cryptographic
   hashing/random APIs.
@@ -190,7 +194,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,650.
+to 12,654.
 
 ## Candidate roadmap
 
@@ -211,7 +215,7 @@ acceptance criteria and a validation command before changing code.
    behavior.
 
 3. **Review other documented partial surfaces by demand.**
-   Examples include `BigInteger` bitwise operations, full UTF-7 behavior,
+   Examples include `BigInteger` shift or byte-array APIs, full UTF-7 behavior,
    debugger/process breadth, and richer XML reader/writer functionality.
    A documented partial API is not automatically higher priority than a
    consumer-visible bug.