🩹 [Patch]: Module startup is faster and performance checks are reproducible (#69)

Module startup is now faster and performance regressions are easier to
catch because the import path was optimized and repeatable benchmark
tooling is included in the repository.

## Changed: Faster module startup

Cold module import is significantly faster in fresh PowerShell sessions,
and parallel session startup is also reduced, so common CLI and
automation entry points spend less time on initialization.

| Metric | Before | After | Δ |
| ------ | ------ | ----- | - |
| Cold import (fresh `pwsh`) | 66.7 ms | **42.3 ms** | **−37%** |
| Parallel runspaces ×4 (import + roundtrip) | 43.5 ms | **28.1 ms** |
**−35%** |
| Per-op (seal / open / keypair) | 104 / 104–121 / 49 µs | 99 / 100–112
/ 46 µs | −4–7% |

## Changed: Reproducible performance verification

The repository now includes benchmark scripts for cold import timing,
per-operation stopwatch measurements, and Profiler traces, so
performance changes can be validated the same way in future PRs.

## Technical Details

- Kept the `Import-Module` assembly-load approach after evaluating
alternatives because `Add-Type -Path` and `Assembly.LoadFrom` were
slower on measured runs.
- Optimized import-time initialization by using a direct runtime path
combine operation and avoiding redundant interop calls for fixed
`crypto_box` size constants.
- Added `tools/benchmark` scripts for local module assembly, stopwatch
benchmarks, import benchmarks, and profiler traces, then cleaned them to
satisfy linter rules.
- Public interfaces remain unchanged, full test suite remains green, and
multi-session behavior (parallel runspaces/processes) is preserved.
- Implementation progress for the linked issue is complete: benchmarked
load strategies, selected the fastest safe path, and documented the
decision in this PR.

<details>
<summary>Related issues</summary>

- Fixes #58

</details>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

.github/mkdocs.yml

@@ -27,5 +27,5 @@ permissions:
 
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@da180bac16b13bfbcdf08b2e4e221b5b49e5ff28 # v6.1.4
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@fb1bdb8fefd243292f779d2a856a38db6fe6daf4 # v6.1.13
     secrets: inherit

.github/workflows/Process-PSModule.yml

@@ -0,0 +1,69 @@
+[project]
+site_name = "Sodium"
+repo_name = "PSModule/Sodium"
+repo_url = "https://github.com/PSModule/Sodium"
+
+[project.theme]
+variant = "classic"
+language = "en"
+logo = "Assets/icon.png"
+favicon = "Assets/icon.png"
+features = [
+    "navigation.instant",
+    "navigation.instant.progress",
+    "navigation.indexes",
+    "navigation.top",
+    "navigation.tracking",
+    "navigation.expand",
+    "search.suggest",
+    "search.highlight",
+    "content.code.copy"
+]
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme)"
+toggle.icon = "lucide/sun-moon"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: dark)"
+scheme = "slate"
+primary = "black"
+accent = "green"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"
+
+[[project.theme.palette]]
+media = "(prefers-color-scheme: light)"
+scheme = "default"
+primary = "indigo"
+accent = "green"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to system preference"
+
+[project.theme.icon]
+repo = "fontawesome/brands/github"
+
+[project.markdown_extensions.toc]
+permalink = true
+
+[project.markdown_extensions.attr_list]
+[project.markdown_extensions.admonition]
+[project.markdown_extensions.md_in_html]
+[project.markdown_extensions.pymdownx.details]
+[project.markdown_extensions.pymdownx.superfences]
+
+[[project.extra.social]]
+icon = "fontawesome/brands/discord"
+link = "https://discord.gg/jedJWCPAhD"
+name = "PSModule on Discord"
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "https://github.com/PSModule/"
+name = "PSModule on GitHub"
+
+[project.extra.consent]
+title = "Cookie consent"
+description = "We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better."
+actions = ["accept", "reject"]

.github/zensical.toml

@@ -203,6 +203,11 @@ public static KeyPairBase64 GenerateKeyPairBase64(string seedText)
         }
 
         public static string DerivePublicKeyBase64(string privateKeyBase64)
+        {
+            return Convert.ToBase64String(DerivePublicKey(privateKeyBase64));
+        }
+
+        public static byte[] DerivePublicKey(string privateKeyBase64)
         {
             ArgumentNullException.ThrowIfNull(privateKeyBase64);
             var privateKey = DecodeBase64Exact(privateKeyBase64, SecretKeyBytes, "private key");
@@ -213,7 +218,7 @@ public static string DerivePublicKeyBase64(string privateKeyBase64)
                 {
                     throw new InvalidOperationException("Unable to derive public key from private key.");
                 }
-                return Convert.ToBase64String(publicKey);
+                return publicKey;
             }
             finally
             {

PSModule/Sodium/Sodium.cs

@@ -0,0 +1,28 @@
+function Assert-SodiumNativeRuntime {
+    <#
+        .SYNOPSIS
+        Provides platform-specific diagnostics after Sodium native initialization fails.
+
+        .DESCRIPTION
+        Checks the Windows Visual C++ runtime after a native initialization exception and throws a targeted message when the required
+        runtime is unavailable.
+
+        .NOTES
+        This function only runs after native library loading fails, which cannot be reproduced safely after the library is loaded in the test process.
+    #>
+    [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverageAttribute()]
+    [OutputType([void])]
+    [CmdletBinding()]
+    param()
+
+    process {
+        if ($IsWindows -and $script:ProcessArchitecture -in @('X64', 'X86')) {
+            $hasRuntime = Assert-VisualCRedistributableInstalled -Version '14.0' -Architecture $script:ProcessArchitecture
+            if (-not $hasRuntime) {
+                $message = "Sodium native initialization failed; the Visual C++ Redistributable for " +
+                "$($script:ProcessArchitecture) appears to be missing or below the required version."
+                throw $message
+            }
+        }
+    }
+}

src/functions/private/Assert-SodiumNativeRuntime.ps1

@@ -23,26 +23,19 @@
             $initializationResult = [PSModule.Sodium]::sodium_init()
         } catch {
             $script:Supported = $false
-            if ($IsWindows) {
-                if ($script:ProcessArchitecture -in @('X64', 'X86')) {
-                    $hasRuntime = Assert-VisualCRedistributableInstalled -Version '14.0' -Architecture $script:ProcessArchitecture
-                    if (-not $hasRuntime) {
-                        $message = "Sodium native initialization failed; the Visual C++ Redistributable for " +
-                        "$($script:ProcessArchitecture) appears to be missing or below the required version."
-                        throw $message
-                    }
-                }
-            }
+            Assert-SodiumNativeRuntime
             throw
         }
         if ($initializationResult -lt 0) {
             throw 'Sodium initialization failed.'
         }
 
-        $script:SodiumPublicKeyBytes = [PSModule.Sodium]::crypto_box_publickeybytes().ToUInt32()
-        $script:SodiumPrivateKeyBytes = [PSModule.Sodium]::crypto_box_secretkeybytes().ToUInt32()
-        $script:SodiumSealBytes = [PSModule.Sodium]::crypto_box_sealbytes().ToUInt32()
-        $script:SodiumSeedBytes = [PSModule.Sodium]::crypto_box_seedbytes().ToUInt32()
+        # Fixed crypto_box constants (curve25519xsalsa20poly1305). The C# layer queries and validates the real
+        # native values at type initialization; hardcoding here avoids four extra interop call sites at import.
+        $script:SodiumPublicKeyBytes = 32u
+        $script:SodiumPrivateKeyBytes = 32u
+        $script:SodiumSealBytes = 48u
+        $script:SodiumSeedBytes = 32u
         $script:SodiumInitialized = $true
     }
 

src/functions/private/Initialize-Sodium.ps1

@@ -0,0 +1,65 @@
+function Resolve-SodiumRuntimeIdentifier {
+    <#
+        .SYNOPSIS
+        Resolves the native Sodium runtime identifier.
+
+        .DESCRIPTION
+        Maps the active operating system and process architecture to the runtime identifier used by the bundled native library.
+    #>
+    [OutputType([string])]
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [System.Runtime.InteropServices.Architecture] $ProcessArchitecture,
+
+        [Parameter()]
+        [switch] $Linux,
+
+        [Parameter()]
+        [switch] $MacOS,
+
+        [Parameter()]
+        [switch] $Windows
+    )
+
+    process {
+        switch ($true) {
+            $Linux {
+                switch ($ProcessArchitecture) {
+                    'Arm64' { return 'linux-arm64' }
+                    'X64' { return 'linux-x64' }
+                    default {
+                        $message = "Unsupported Linux process architecture: $ProcessArchitecture. " +
+                        'Please refer to the documentation for supported architectures.'
+                        throw $message
+                    }
+                }
+            }
+            $MacOS {
+                switch ($ProcessArchitecture) {
+                    'Arm64' { return 'osx-arm64' }
+                    'X64' { return 'osx-x64' }
+                    default {
+                        $message = "Unsupported macOS process architecture: $ProcessArchitecture. " +
+                        'Please refer to the documentation for supported architectures.'
+                        throw $message
+                    }
+                }
+            }
+            $Windows {
+                switch ($ProcessArchitecture) {
+                    'X64' { return 'win-x64' }
+                    'X86' { return 'win-x86' }
+                    default {
+                        $message = "Unsupported Windows process architecture: $ProcessArchitecture. " +
+                        'Please refer to the documentation for supported architectures.'
+                        throw $message
+                    }
+                }
+            }
+            default {
+                throw 'Unsupported platform. Please refer to the documentation for more information.'
+            }
+        }
+    }
+}

src/functions/private/Resolve-SodiumRuntimeIdentifier.ps1

@@ -68,10 +68,6 @@
         [string] $PrivateKey
     )
 
-    begin {
-        Initialize-Sodium
-    }
-
     process {
         try {
             if (-not [string]::IsNullOrWhiteSpace($PublicKey)) {

src/functions/public/ConvertFrom-SodiumSealedBox.ps1

@@ -55,10 +55,6 @@
         [ValidateNotNullOrEmpty()]
         [string] $PublicKey
     )
-    begin {
-        Initialize-Sodium
-    }
-
     process {
         try {
             return [PSModule.Sodium]::SealBase64($Message, $PublicKey)

src/functions/public/ConvertTo-SodiumSealedBox.ps1

@@ -67,6 +67,10 @@
         https://psmodule.io/Sodium/Functions/Get-SodiumPublicKey/
     #>
 
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+        'PSUseOutputTypeCorrectly', '',
+        Justification = 'The unary comma preserves the byte array as one pipeline object.'
+    )]
     [OutputType([string], ParameterSetName = 'Base64')]
     [OutputType([byte[]], ParameterSetName = 'AsByteArray')]
     [CmdletBinding(DefaultParameterSetName = 'Base64')]
@@ -81,14 +85,10 @@
         [switch] $AsByteArray
     )
 
-    begin {
-        Initialize-Sodium
-    }
-
     process {
         if ($AsByteArray) {
             try {
-                return [System.Convert]::FromBase64String([PSModule.Sodium]::DerivePublicKeyBase64($PrivateKey))
+                return , ([PSModule.Sodium]::DerivePublicKey($PrivateKey))
             } catch [System.Management.Automation.MethodInvocationException] {
                 throw $_.Exception.InnerException
             }
@@ -100,5 +100,4 @@
         }
     }
 
-    end {}
 }