Gov.Protocol 1.0.0

There is a newer version of this package available.
See the version list below for details.

dotnet add package Gov.Protocol --version 1.0.0

NuGet\Install-Package Gov.Protocol -Version 1.0.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="Gov.Protocol" Version="1.0.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="Gov.Protocol" Version="1.0.0" />
                    

                            Directory.Packages.props

<PackageReference Include="Gov.Protocol" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add Gov.Protocol --version 1.0.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: Gov.Protocol, 1.0.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package Gov.Protocol@1.0.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=Gov.Protocol&version=1.0.0
                    

                            Install as a Cake Addin

#tool nuget:?package=Gov.Protocol&version=1.0.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

Build Reliability Governor

Prevents C++ build systems from freezing your machine or failing silently due to memory exhaustion.

NuGet Packages

Package	Description
`Gov.Protocol`	Shared message DTOs for client-service communication over named pipes. Token requests, grants, heartbeats, and failure classification.
`Gov.Common`	Windows memory metrics, OOM failure classification, and named-pipe client. Commit-charge monitoring and token-budget calculation.

The Problem

Parallel C++ builds (cmake --parallel, msbuild /m, ninja -j) can easily exhaust system memory:

Each cl.exe instance can use 1-4 GB RAM (templates, LTCG, heavy headers)
Build systems launch N parallel jobs and hope for the best
When RAM exhausts: system freeze, or CL.exe exited with code 1 (no diagnostic)
The killer metric is Commit Charge, not "free RAM"

The Solution

A lightweight governor that sits between your build system and the compiler:

Adaptive concurrency based on commit charge, not job count
Silent failure → actionable diagnosis: "Memory pressure detected, recommend -j4"
Auto-throttling: builds slow down instead of crashing
Fail-safe: if governor is down, tools run ungoverned

Quick Start

# 1. Build
cd build-governor
dotnet build -c Release
dotnet publish src/Gov.Wrapper.CL -c Release -o bin/wrappers
dotnet publish src/Gov.Wrapper.Link -c Release -o bin/wrappers
dotnet publish src/Gov.Cli -c Release -o bin/cli

# 2. Start governor (in one terminal)
dotnet run --project src/Gov.Service -c Release

# 3. Run your build (in another terminal)
bin/cli/gov.exe run -- cmake --build . --parallel 16

How It Works

                    ┌─────────────────┐
                    │  Gov.Service    │
                    │  (Token Pool)   │
                    │  - Monitor RAM  │
                    │  - Grant tokens │
                    │  - Classify OOM │
                    └────────┬────────┘
                             │ Named Pipe
         ┌───────────────────┼───────────────────┐
         │                   │                   │
    ┌────┴────┐        ┌────┴────┐        ┌────┴────┐
    │ cl.exe  │        │ cl.exe  │        │link.exe │
    │ wrapper │        │ wrapper │        │ wrapper │
    └────┬────┘        └────┬────┘        └────┬────┘
         │                   │                   │
    ┌────┴────┐        ┌────┴────┐        ┌────┴────┐
    │ real    │        │ real    │        │ real    │
    │ cl.exe  │        │ cl.exe  │        │ link.exe│
    └─────────┘        └─────────┘        └─────────┘

Token Cost Model

Action	Tokens	Notes
Normal compile	1	Baseline
Heavy compile (Boost/gRPC)	2-4	Template-heavy
Compile with /GL	+3	LTCG codegen
Link	4	Base link cost
Link with /LTCG	8-12	Full LTCG

Throttle Levels

Commit Ratio	Level	Behavior
< 80%	Normal	Grant tokens immediately
80-88%	Caution	Slower grants, delay 200ms
88-92%	SoftStop	Significant delays, 500ms
> 92%	HardStop	Refuse new tokens

Failure Classification

When a build tool exits with an error, the governor classifies it:

LikelyOOM: High commit ratio + process peaked high + no compiler diagnostics
LikelyPagingDeath: Moderate pressure signals
NormalCompileError: Compiler diagnostics present in stderr
Unknown: Can't determine

On OOM, you see:

╔══════════════════════════════════════════════════════════════════╗
║  BUILD FAILED: Memory Pressure Detected                          ║
╠══════════════════════════════════════════════════════════════════╣
║  Exit code: 1                                                    ║
║  System commit: 94% (45.2 GB / 48.0 GB)                          ║
║  Process peak:  3.1 GB                                           ║
╠══════════════════════════════════════════════════════════════════╣
║  Recommendation: Reduce parallelism                              ║
║    CMAKE_BUILD_PARALLEL_LEVEL=4                                  ║
║    MSBuild: /m:4                                                 ║
║    Ninja: -j4                                                    ║
╚══════════════════════════════════════════════════════════════════╝

Safety Features

Fail-safe: If governor unavailable, wrappers run tools ungoverned
Lease TTL: If wrapper crashes, tokens auto-reclaim after 30 min
No deadlock: Timeouts on all pipe operations
Tool auto-detection: Uses vswhere to find real cl.exe/link.exe

CLI Commands

# Run a governed build
gov run -- cmake --build . --parallel 16

# Check governor status
gov status

# Run without auto-starting governor
gov run --no-start -- ninja -j 8

Environment Variables

Variable	Description
`GOV_REAL_CL`	Path to real cl.exe (auto-detected)
`GOV_REAL_LINK`	Path to real link.exe (auto-detected)
`GOV_ENABLED`	Set by `gov run` to indicate governed mode

Project Structure

build-governor/
├── src/
│   ├── Gov.Protocol/    # Shared DTOs
│   ├── Gov.Common/      # Windows metrics, classifier
│   ├── Gov.Service/     # Background governor
│   ├── Gov.Wrapper.CL/  # cl.exe shim
│   ├── Gov.Wrapper.Link/# link.exe shim
│   └── Gov.Cli/         # `gov` command
├── bin/
│   ├── wrappers/        # Published shims
│   └── cli/             # Published CLI
└── gov-env.cmd          # Manual PATH setup

License

MIT

Product	Compatible and additional computed target framework versions.
.NET	net9.0 is compatible. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Product

.NET

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net9.0
- No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Gov.Protocol:

Package	Downloads
Gov.Common Windows memory metrics, OOM failure classification, and named-pipe client for Build Governor. Provides commit-charge monitoring, token-budget calculation, and process-level memory tracking.	281

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
1.0.2	91	2/26/2026
1.0.1	94	2/23/2026
1.0.0	115	2/12/2026