diff --git a/.claude/skills/run-socktuner/.gitignore b/.claude/skills/run-socktuner/.gitignore deleted file mode 100644 index f16baf5..0000000 --- a/.claude/skills/run-socktuner/.gitignore +++ /dev/null @@ -1 +0,0 @@ -shots/ diff --git a/.claude/skills/run-socktuner/SKILL.md b/.claude/skills/run-socktuner/SKILL.md deleted file mode 100644 index b329739..0000000 --- a/.claude/skills/run-socktuner/SKILL.md +++ /dev/null @@ -1,173 +0,0 @@ ---- -name: run-socktuner -description: Build, launch, drive and screenshot the SockTuner WPF desktop app on Windows. Use when asked to run, start, open, screenshot, inspect the UI of, or verify a change in the real app rather than in tests. ---- - -# Run SockTuner - -SockTuner is a **WPF desktop app on Windows** (.NET 10, `net10.0-windows`). There is no -DOM and no CDP, so it is driven through **Windows UI Automation** by -[`driver.ps1`](driver.ps1) — tabs are selected **by name**, never by screen coordinate. - -All paths below are relative to the repo root. The driver must run under **Windows -PowerShell 5.1 (`powershell.exe`)**, not `pwsh` 7: `UIAutomationClient` is a .NET -Framework assembly. - -## Prerequisites - -The .NET 10 SDK, already present if `dotnet build` works. Nothing to `apt-get` — this is -Windows, and the driver uses only in-box assemblies (`UIAutomationClient`, -`UIAutomationTypes`, `System.Drawing`, `user32.dll`). - -## Agent path — the driver - -```bash -powershell.exe -NoProfile -File .claude/skills/run-socktuner/driver.ps1 [arg] -``` - -| Command | What it does | -| --- | --- | -| `build` | `dotnet build src/SockTuner/SockTuner.csproj -c Release` | -| `launch` | Starts the app **detached** and waits for its window | -| `status` | pid / responding / RAM | -| `tabs` | Lists the navigation entries; `*` marks the selected one | -| `select ""` | Selects a tab by name (substring match) | -| `shot [path]` | PNG of the window → `.claude/skills/run-socktuner/shots/` | -| `stop` | Kills the process | - -A full verified cycle: - -```bash -D=.claude/skills/run-socktuner/driver.ps1 -powershell.exe -NoProfile -File $D build -powershell.exe -NoProfile -File $D launch -powershell.exe -NoProfile -File $D select "NDIS" -powershell.exe -NoProfile -File $D shot -powershell.exe -NoProfile -File $D stop -``` - -Observed output of that sequence: - -```text -OK build -> C:\...\src\SockTuner\bin\Release\net10.0-windows\SockTuner.exe -OK launched pid=8456 window='SockTuner' -OK selected 'NDIS & drivers' -OK shot 1320x820 -> C:\...\.claude\skills\run-socktuner\shots\socktuner-20260828-022129.png -OK stopped -``` - -**Read the screenshot back** with the Read tool. A blank frame means the window never -painted. A correct `NDIS & drivers` capture shows *"Driver-advertised NDIS properties"* -and a grid of real keywords (`*InterruptModeration`, `*EEE`, `ITR`, `*FlowControl`, -`*JumboPacket`) with current/default values. - -The 20 tabs, in five groups. `tabs` also prints the group headings — `OVERVIEW`, -`INVENTORY`, `MEASURE`, `ACT`, `RECORDS` — which are disabled `TabItem`s used as -navigation scenery. They are not selectable: `select "INVENTORY"` fails by design. - -| Group | Tabs | -| --- | --- | -| OVERVIEW | `Dashboard` | -| INVENTORY | `Adapters`, `NDIS & drivers`, `Routes & DNS`, `Network profiles`, `Network bindings`, `Offloads`, `TCP settings`, `QoS policies`, `Winsock catalog` | -| MEASURE | `Gaming diagnostics`, `Throughput & bufferbloat`, `DNS resolvers` | -| ACT | `Interfaces`, `Recommendations`, `Interrupt affinity`, `Tuning plan` | -| RECORDS | `Tools & references`, `History & comparison`, `Preferences` | - -Keyboard: **F5** refreshes the inventory, **Ctrl+F** focuses the global search, **Ctrl+K** -jumps to the section whose name matches what is typed there, and **Ctrl+1..9** select the -first nine selectable tabs. The window remembers its size and position between runs, unless -the saved position no longer lands on an attached monitor. - -`Tuning plan` used to be last; it now sits with the other surfaces that act. The reference -links moved out of `Preferences` into `Tools & references`. - -## Compatibility reports - -Compatibility reports are intentionally created only through the visible UI flow under -**Preferences → Help improve SockTuner**. The user reviews the complete JSON before saving -and explicitly chooses whether to open the GitHub issue form. The agent driver does not -bypass that consent flow. - -## Tests - -```bash -dotnet test SockTuner.sln -``` - -The default suite reports its current pass/skip counts. Skipped tests are read-only -live-inventory checks against real adapters; they are safe on a normal desktop and mutate -nothing: - -```bash -SOCKTUNER_LIVE_INVENTORY=1 dotnet test SockTuner.sln -``` - -## Never run these on a real machine - -`--verify-tcp-writes` **writes to the live TCP stack** and `--verify-device-writes` -**enables and disables a real adapter, writes PnPCapabilities and creates a QoS policy**. -Both are gated behind `SOCKTUNER_VM_WRITE_TEST=1`, so an argument alone cannot trigger -them, and both belong in a disposable VM only. The driver deliberately exposes no command -for either. - -### Running a write validation in the VM - -`D:\VmLab\SockTuner-Win11-Base` is the guest. Checkpoint first, then: - -```powershell -$vm = Get-VM | ? Name -eq 'SockTuner-Win11-Base' # -Name fails, see gotcha below -$cred = Get-Credential # the guest account -$vm | Copy-VMFile -SourcePath -DestinationPath 'C:\SockTunerValidate\SockTuner.exe' ` - -CreateFullPath -FileSource Host -Force -Invoke-Command -VMId $vm.Id -Credential $cred -ScriptBlock { - $env:SOCKTUNER_VM_WRITE_TEST = '1' - Start-Process 'C:\SockTunerValidate\SockTuner.exe' -ArgumentList '--verify-device-writes' - # then poll the guest Desktop for socktuner-device-write-verification-*.json -} -``` - -**Do not trust the report alone.** It only checks each setting's own value. Compare the -guest's registry and adapter state either side of the run: that is what caught an empty -`…\Windows\QoS` container being left behind by a rollback that the report called clean. - -The guest needs a second network adapter (`Add-VMNetworkAdapter`) or the enable/disable -path is skipped — the run refuses to disable the adapter carrying the default route. - -## Gotchas - -- **`Start-Process`, never `& $exe` or `exe &`.** Launched as a child of the agent's shell, - the app dies when that shell call returns — it disappears mid-session and looks like a - crash. The driver's `launch` uses `Start-Process`. -- **Never click tabs by coordinate.** The navigation list scrolls, so coordinates read a - moment earlier select the *wrong* tab, or miss the window entirely and land on whatever - is behind it. The driver uses UIA `SelectionItemPattern.Select()` by name and is immune - to this. Coordinate clicking failed three times in a row before the driver existed. -- **A background process cannot raise a window by asking.** `SetForegroundWindow` returns - `true` and does nothing when the caller does not already own the foreground, so a shot - silently captured whatever browser was on top instead. `driver.ps1 shot` now shares the - input queue of the current foreground window for the length of the call - (`AttachThreadInput`), retries once, and **throws** rather than saving a screenshot of the - wrong window. If it throws, close or minimise what is covering the app. -- **Screenshot tooling downscales.** A desktop-capture MCP may return an image scaled from - 3640x2144 to ~1833x1080, so coordinates read off that image are wrong by a ~1.99 factor. - `driver.ps1 shot` captures the window rect at native size and sidesteps this. -- **`pwsh` 7 cannot load `UIAutomationClient`.** Use `powershell.exe`. -- **A stale VM registration breaks every `-Name` Hyper-V cmdlet on this host.** `Get-VM`, - `Checkpoint-VM -Name`, `Copy-VMFile -Name` and friends enumerate all VMs first, hit the - broken registration and throw "the object was not found" — while still returning the good - VMs. Get the object and pipe it instead: `Get-VM | ? Name -eq '…' | Copy-VMFile …`. -- **PowerShell Direct runs over VMBus, not the network.** That is what makes it safe to - disable an adapter in the guest from the host: the session survives losing all guest - networking. It does need guest credentials; there is no passwordless path. -- **A verification-mode run has no console over PowerShell Direct.** The verification - modes attach to the caller's console when there is one and fall back to a message box when - there is not. Start them detached in the disposable VM and poll for their JSON result. - -## Troubleshooting - -| Symptom | Fix | -| --- | --- | -| `SockTuner window not found. Run "launch" first.` | The app is not running, or it was started as a shell child and already died. Re-run `launch`. | -| `Not built. Run: driver.ps1 build` | The Release exe is missing. Run `build`. | -| `No tab matching ''` | Run `tabs` for the exact names; matching is substring, case-insensitive. | -| `Could not raise the SockTuner window; another window is on top…` | Something is covering the app and Windows refused the foreground handover. Minimise it, or click the SockTuner window once, then re-run `shot`. | diff --git a/.claude/skills/run-socktuner/driver.ps1 b/.claude/skills/run-socktuner/driver.ps1 deleted file mode 100644 index 2d2f515..0000000 --- a/.claude/skills/run-socktuner/driver.ps1 +++ /dev/null @@ -1,172 +0,0 @@ -<# - SockTuner agent driver. - - A WPF app has no DOM and no CDP, so this drives it through Windows UI Automation: - tabs are selected by NAME, never by screen coordinate. That matters — the navigation - list scrolls, so coordinates captured a moment ago silently select the wrong tab or - land on whatever window is behind. - - Run under Windows PowerShell 5.1 (powershell.exe), not pwsh 7: UIAutomationClient is - a .NET Framework assembly. - - powershell.exe -NoProfile -File .claude\skills\run-socktuner\driver.ps1 [arg] -#> -param( - [Parameter(Position = 0)][string]$Command = 'help', - [Parameter(Position = 1)][string]$Arg -) - -$ErrorActionPreference = 'Stop' -$Root = (Resolve-Path (Join-Path $PSScriptRoot '..\..\..')).Path -$Exe = Join-Path $Root 'src\SockTuner\bin\Release\net10.0-windows\SockTuner.exe' -$ShotDir = Join-Path $Root '.claude\skills\run-socktuner\shots' - -function Load-Uia { - Add-Type -AssemblyName UIAutomationClient, UIAutomationTypes, System.Drawing | Out-Null - if (-not ('Win32Rect' -as [type])) { - Add-Type @' -using System; -using System.Runtime.InteropServices; -public class Win32Rect { - [StructLayout(LayoutKind.Sequential)] public struct RECT { public int Left, Top, Right, Bottom; } - [DllImport("user32.dll")] public static extern bool GetWindowRect(IntPtr h, out RECT r); - [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr h); - [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr h, int c); - [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow(); - [DllImport("user32.dll")] public static extern bool BringWindowToTop(IntPtr h); - [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr h, IntPtr pid); - [DllImport("user32.dll")] public static extern bool AttachThreadInput(uint from, uint to, bool attach); - [DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId(); - - // Windows refuses SetForegroundWindow to a process that does not already own the - // foreground, and returns true anyway. Sharing the input queue of whatever does own it - // for the length of the call is the documented way through, and without it a shot - // silently captures the window that is actually on top instead. - public static void Raise(IntPtr h) { - IntPtr fg = GetForegroundWindow(); - uint mine = GetCurrentThreadId(); - uint theirs = GetWindowThreadProcessId(fg, IntPtr.Zero); - bool attached = theirs != 0 && theirs != mine && AttachThreadInput(mine, theirs, true); - ShowWindow(h, 9); // SW_RESTORE - BringWindowToTop(h); - SetForegroundWindow(h); - if (attached) AttachThreadInput(mine, theirs, false); - } -} -'@ - } -} - -function Get-Window { - param([int]$TimeoutSeconds = 30) - Load-Uia - $deadline = (Get-Date).AddSeconds($TimeoutSeconds) - while ((Get-Date) -lt $deadline) { - $cond = New-Object System.Windows.Automation.PropertyCondition( - [System.Windows.Automation.AutomationElement]::NameProperty, 'SockTuner') - $win = [System.Windows.Automation.AutomationElement]::RootElement.FindFirst( - [System.Windows.Automation.TreeScope]::Children, $cond) - if ($win) { return $win } - Start-Sleep -Milliseconds 400 - } - throw 'SockTuner window not found. Run "launch" first.' -} - -function Get-Tabs { - param($Window) - $cond = New-Object System.Windows.Automation.PropertyCondition( - [System.Windows.Automation.AutomationElement]::ControlTypeProperty, - [System.Windows.Automation.ControlType]::TabItem) - return $Window.FindAll([System.Windows.Automation.TreeScope]::Descendants, $cond) -} - -switch ($Command) { - - 'build' { - & dotnet build (Join-Path $Root 'src\SockTuner\SockTuner.csproj') -c Release --nologo -v q - if ($LASTEXITCODE -ne 0) { throw "Build failed ($LASTEXITCODE)." } - "OK build -> $Exe" - } - - # Start-Process, never "& $Exe" or a background job: a child of the agent's shell dies - # when that shell call returns, and the app vanishes mid-session. - 'launch' { - if (-not (Test-Path $Exe)) { throw "Not built. Run: driver.ps1 build" } - if (Get-Process SockTuner -ErrorAction SilentlyContinue) { "already running"; break } - Start-Process -FilePath $Exe -WorkingDirectory (Split-Path $Exe) - $win = Get-Window - $p = Get-Process SockTuner - "OK launched pid=$($p.Id) window='$($win.Current.Name)'" - } - - 'status' { - $p = Get-Process SockTuner -ErrorAction SilentlyContinue - if ($p) { "running pid=$($p.Id) responding=$($p.Responding) ram=$([math]::Round($p.WorkingSet64/1MB,1))MB" } - else { 'not running' } - } - - 'tabs' { - foreach ($t in (Get-Tabs (Get-Window))) { - $sel = $t.GetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern) - $mark = if ($sel.Current.IsSelected) { '*' } else { ' ' } - "$mark $($t.Current.Name)" - } - } - - # Selects by name through the SelectionItemPattern. Immune to the scrolling nav list. - 'select' { - if (-not $Arg) { throw 'Usage: driver.ps1 select ""' } - $win = Get-Window - $match = $null - foreach ($t in (Get-Tabs $win)) { - if ($t.Current.Name -like "*$Arg*") { $match = $t; break } - } - if (-not $match) { throw "No tab matching '$Arg'. Run: driver.ps1 tabs" } - $match.GetCurrentPattern([System.Windows.Automation.SelectionItemPattern]::Pattern).Select() - Start-Sleep -Milliseconds 700 - "OK selected '$($match.Current.Name)'" - } - - 'shot' { - $win = Get-Window - $h = [IntPtr]$win.Current.NativeWindowHandle - [Win32Rect]::Raise($h) - Start-Sleep -Milliseconds 600 - if ([Win32Rect]::GetForegroundWindow() -ne $h) { - [Win32Rect]::Raise($h) - Start-Sleep -Milliseconds 600 - } - if ([Win32Rect]::GetForegroundWindow() -ne $h) { - throw "Could not raise the SockTuner window; another window is on top and the shot would capture it." - } - $r = New-Object Win32Rect+RECT - [void][Win32Rect]::GetWindowRect($h, [ref]$r) - $w = $r.Right - $r.Left; $ht = $r.Bottom - $r.Top - New-Item -ItemType Directory -Force -Path $ShotDir | Out-Null - $path = if ($Arg) { $Arg } else { Join-Path $ShotDir ("socktuner-{0:yyyyMMdd-HHmmss}.png" -f (Get-Date)) } - $bmp = New-Object System.Drawing.Bitmap $w, $ht - $g = [System.Drawing.Graphics]::FromImage($bmp) - $g.CopyFromScreen($r.Left, $r.Top, 0, 0, $bmp.Size) - $bmp.Save($path, [System.Drawing.Imaging.ImageFormat]::Png) - $g.Dispose(); $bmp.Dispose() - "OK shot ${w}x${ht} -> $path" - } - - 'stop' { - Get-Process SockTuner -ErrorAction SilentlyContinue | Stop-Process -Force - 'OK stopped' - } - - default { -@' -SockTuner driver — commands: - build dotnet build Release - launch start detached, wait for the window - status pid / responding / RAM - tabs list navigation tabs, * marks the selected one - select "" select a tab by name (substring match) - shot [path] PNG of the window -> .claude/skills/run-socktuner/shots/ - stop kill the process -'@ - } -} diff --git a/.gitignore b/.gitignore index 248ca80..c739b72 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,9 @@ __pycache__/ # IDE and user state .vs/ .idea/ +.claude/ +.pi/ +AGENTS.md *.user *.suo *.userosscache diff --git a/.pi/agents/supervisor.md b/.pi/agents/supervisor.md deleted file mode 100644 index 8917cc0..0000000 --- a/.pi/agents/supervisor.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -name: supervisor -description: Read-only phase gate for SockTuner correctness, safety, tests, and release readiness -tools: read, grep, find, ls, bash -model: openrouter/moonshotai/kimi-k3 ---- - -You are SockTuner's independent phase supervisor. Review the current phase before it is committed. - -Hard rules: -- Never edit files, commit, push, install software, or launch the application. -- Bash is limited to read-only inspection plus safe build/test commands (`git diff`, `git status`, `git log`, `dotnet build`, `dotnet test`). -- Never execute a network tweak, write the Windows registry, restart an adapter, change DNS/MTU/QoS, or run scripts/binaries under `research/`. -- Treat the real Windows host as production. Mutation backends may only be reviewed statically; tests must use fakes or simulation unless explicitly marked for a disposable VM. - -Review procedure: -1. Inspect `git status`, the complete staged/unstaged diff, and relevant surrounding files. -2. Check correctness, privilege-boundary safety, rollback behavior, command/registry injection risk, localization assumptions, and accidental host mutation. -3. Run the smallest relevant safe build and test commands. -4. Check that documentation and CI match actual behavior. -5. Return a phase verdict. - -Output exactly: - -## Verdict -`PASS` or `FAIL` - -## Must Fix -- Concrete issue with file and line, or `None`. - -## Warnings -- Non-blocking issue, or `None`. - -## Checks -- Commands run and results. - -A phase passes only when it builds, tests pass, no host-mutating test can run by default, and there are no critical correctness or security issues. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index fedc871..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,35 +0,0 @@ -# SockTuner Development Rules - -## Safety - -- Never execute network mutations on the development host. -- Never run scripts or binaries under `research/`. -- Mutation tests must use an in-memory/fake platform. Real Windows integration tests must be explicitly opt-in and reserved for a disposable VM. -- Do not restart adapters, change registry/network settings, DNS, MTU, QoS, Winsock, routes, bindings, or power state during development. -- Read-only Windows inventory and diagnostics may run locally. - -## Architecture - -- C#/.NET 10 LTS, WPF, x64-first Windows 10/11 desktop application. -- Native/API-first; no PowerShell runtime dependency and no arbitrary shell execution. -- One production application project and one test project until a split is justified. -- Normally unelevated UI; typed allowlisted elevated worker for future mutation operations. -- Every writable setting requires snapshot, validation, read-back verification, and exact rollback. - -## Workflow - -1. Work in a small roadmap phase. -2. Build and run safe tests. -3. Ask the project `supervisor` agent for a read-only phase gate. -4. Fix blocking findings. -5. Commit only after a PASS verdict. -6. Push after the completed set of phases. - -## Commands - -```bash -dotnet restore -dotnet build --no-restore -dotnet test --no-build -dotnet format --verify-no-changes -``` diff --git a/README.md b/README.md index 71ca1f2..f596a81 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,3 @@ -

- SockTuner banner -

-

Last commit GitHub stars @@ -58,7 +54,7 @@ The report contains the adapter model, driver version, OS version, and driver-ad | Change management | Dry run, compatibility gates, risk labels, snapshots, read-back verification, audit history, export, and exact rollback | | Profiles | Transparent, editable profiles built only from independently supported and tested settings | -See the [Documentation Index](docs/README.md) and [Product Scope](docs/PRODUCT_SCOPE.md) for the proposed feature boundary. +See the [documentation index](docs/README.md) for the architecture and repository metadata. ## Proposed technology @@ -70,14 +66,12 @@ See the [Documentation Index](docs/README.md) and [Product Scope](docs/PRODUCT_S WPF is the deliberate choice for a Windows-only administrative tool: it is mature, works across Windows 10 and 11, integrates cleanly with native Windows management surfaces, and avoids a browser runtime or an unnecessary UI platform dependency. -Read the full [Architecture](docs/ARCHITECTURE.md), [Implementation Roadmap](docs/ROADMAP.md), and [Development Guide](docs/DEVELOPMENT.md). +Read the full [Architecture](docs/ARCHITECTURE.md) and [GitHub repository metadata](docs/GITHUB.md). ## Engineering position Network settings are workload-, driver-, OS-, and topology-dependent. Disabling RSS, ECN, auto-tuning, offloads, or interrupt moderation is not universally beneficial. Nagle-related changes affect TCP, while many games primarily use UDP. Client-side throttling is not a universal replacement for router-side SQM/AQM and cannot eliminate every form of bufferbloat. -The reference scripts in this private workspace are research inputs, not production code or verified recommendations. Their conflicting values and undocumented registry edits must be validated against official documentation, driver-advertised capabilities, repeatable benchmarks, and rollback tests before they can become SockTuner features. - ## Current stage - Native read-only inventory covers adapters, routes, interfaces, DNS, profiles, bindings, NIC counters, TCP templates, QoS, offloads, interrupts, Winsock, driver identity, and driver-advertised properties. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 71c13da..2e5490b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -71,7 +71,7 @@ These are folders/namespaces in one production project, not separate assemblies | Platform.Windows | Small wrappers around Windows APIs, CIM/WMI, and registry access | | Persistence | Versioned JSON snapshots, reports, preferences, and logs | -A plugin API, dependency-injection framework, command bus, database, cloud backend, and background agent are not needed for the first release. +A plugin API, dependency-injection framework, command bus, database, cloud backend, and background service are not needed for the first release. ## 5. Windows integration strategy diff --git a/docs/DELIVERY_PLAN.md b/docs/DELIVERY_PLAN.md deleted file mode 100644 index 8882571..0000000 --- a/docs/DELIVERY_PLAN.md +++ /dev/null @@ -1,263 +0,0 @@ -# SockTuner delivery plan — diagnose, localise, fix - -Detailed expansion of [ROADMAP](ROADMAP.md) steps 8–10. The roadmap says *what* ships in each -step; this says *how*, and tracks the remaining work as independent workstreams. - -## Product goal - -Diagnose the whole chain — NIC and driver, LAN, router, access link, ISP, external hops, remote -endpoint — then fix what SockTuner legitimately controls, guide precisely on what it does not, -and be explicit about what nobody local can fix. - -## Non-negotiable architecture - -**Three layers, no leakage between them.** Each is separately testable and extendable. - -| Layer | Namespace | Responsibility | Must never | -| --- | --- | --- | --- | -| Collection | `Services.Collection` | Probes, tests, inventory. Produces facts. | Interpret or judge | -| Diagnosis | `Services.Diagnosis` | Classify problem, locate segment, assign owner. Pure functions over collected facts. | Touch the network or the system | -| Remediation | `Services.Remediation` | Propose and apply reversible actions. | Decide *whether* there is a problem | - -Diagnosis takes collected data in and returns findings out. Every classification rule is therefore -testable against a fixture with no network and no host mutation — the property the existing suite -already relies on. - -**Every automatic action is logged and reversible.** Remediation emits change requests that flow -through the existing `SettingTransactionService`: snapshot → apply → read-back verify → audit → -exact rollback. No remediation path may write outside that engine. - -## Responsibility model - -Every finding carries exactly one owner. This is the spine of the product: it decides what the -user is shown and what SockTuner is allowed to do. - -| Owner | Meaning | SockTuner behaviour | -| --- | --- | --- | -| `Automatic` | Safe, reversible, no user choice needed | Offer one-click apply (still previewed and audited) | -| `PresetOrManual` | Needs a target or a judgement call | Offer presets (bandwidth / max ping / max jitter, or use-case profile) or manual edit | -| `Router` | Needs router configuration | Give the specific parameter, expected value and reason; apply via OpenWrt SSH when explicitly enabled | -| `OutOfScope` | ISP or infrastructure limit | Diagnose precisely, explain, export evidence. Never attempt a fix | - -Router guidance must be actionable: *which* parameter, *what* value, *why*. "Check your QoS -settings" is not acceptable output. - ---- - -## Workstreams - -### W1 — Routing diagnosis — **done** - -Per-hop quality, not a single traceroute. - -- `HopMeasurement`: TTL, address, per-hop statistics, private / CGNAT / public classification. -- `RoutePathDiagnostic`: repeated multi-hop sampling (mtr-style), hop stability across rounds, - route-change detection. -- Rate-limit awareness: an intermediate hop that deprioritises ICMP shows loss *at that hop* but - not beyond it. A hop is only called faulty when the degradation **persists downstream**. This is - the most common false positive in traceroute-based tools, and the rule that prevents it is the - core of this workstream. - -### W2 — Bottleneck localisation — **done** - -Where the chain first degrades, not just that it does. - -- `NetworkSegment`: LocalNicDriver → Lan → RouterOrAccess → IspAccess → IspCore → ExternalHop → - RemoteEndpoint. -- `BottleneckLocator` walks the chain outward and returns the first segment where latency, jitter - or loss steps up beyond threshold, with supporting and contradicting observations. -- Local evidence (NIC error and discard counters, link speed, driver power settings) is folded in, - so a local driver fault is not misattributed to the ISP. -- **Inconclusive stays a valid result.** - -### W3 — Responsibility assignment — **done** - -- Owner on every finding, per the table above. -- `ResponsibilityAssigner` maps (segment, problem kind, local capability) → owner. -- The owner is *derived*, never hand-written per finding, so it cannot drift between findings. - -### W4 — Probe archive and device coverage — **done** - -- `alpha-tester-output/` becomes the tracked capability archive: one file per adapter model, named - `--.json`, plus a generated `INDEX.md` showing covered versus missing - hardware so gaps are visible at a glance. -- Probe output enriched with the structured CIM constraints (valid values, min/max/step, default) - already used by the tuning path, so archive entries and the live tuning surface share one shape. -- Wi-Fi adapters use the identical structure as Ethernet — no separate Wi-Fi format. - -### W5 — Active measurement suite — **done** - -- `ThroughputProbe`: multi-stream HTTP against a chosen endpoint, user-initiated only, bounded - window. A run stopped early keeps its rate and is labelled incomplete rather than discarded. -- `LoadedLatencyProbe`: the same latency probe measured idle and again while one direction is - saturated, with the load stopped as soon as the measurement window closes. -- `LoadedLatencyAnalyzer`: latency-increase grade (A+ to F), plus loaded jitter and loss increase. - The bufferbloat *finding* is owned by the router — the queue is not on the endpoint, and shaping - it there costs no throughput. W10 adds the endpoint-side **mitigation** beside it for the case - where the router is not the user's to configure; it is labelled a mitigation, never a fix. -- Long-window stability: `NetworkMonitorService` already samples for minutes to hours with bounded - memory and explicit start and stop; `StabilityAnalyzer` finds the loss bursts and latency spikes - inside that window, judged against the run's own baseline. Two consecutive bad samples make an - episode; one is noise. A truncated window says so in its verdict. -- Local saturation: `LinkUtilization` turns adapter counter deltas into a rate, and a baseline - taken while this machine was filling its own link is reported as such instead of being graded. - The NIC link speed is a poor capacity proxy, so saturation is claimed against a *measured* - capacity where one exists. Per-process attribution needs ETW and stays deferred. - -### W6 — Topology and path facts — **done** - -- `TopologyAnalyzer`: CGNAT and double NAT from the route, the router-reported WAN address and the - observed public address — all three optional, and the verdict degrades to `Unknown` rather than - guessing. CGNAT is `OutOfScope` and stated not to cost latency; double NAT is `Router` with the - exact fix (bridge mode, or one device stops translating). Two private hops before the first - public one are only medium confidence: some ISPs number their own access equipment out of - private space. The router-reported WAN address arrives with W8; the observed public address - needs an external reflector and is only fetched on explicit request. -- PMTUD black hole: a DF probe that times out is retried fragmentable. If the same packet gets - through, the path drops oversized packets silently — `PathMtuState.IcmpBlackHole` — and the - workaround is local and exact even though the cause is not. -- Wi-Fi radio: `WindowsWifiInventory` reads RSSI, band, channel and occupied width through the - native WLAN API, taking the *cached* scan so the radio is never interrupted. Width comes from the - beacon's HT/VHT operation elements, so a 40 or 80 MHz neighbour is counted across the spectrum it - really occupies rather than the channel number it advertises. `WifiRadioAnalyzer` separates weak - signal (placement), wrong band (the same SSID reachable on 5/6 GHz) and channel congestion - (`Router`, with an exact 2.4 GHz channel — 1, 6 and 11 are legal everywhere, which is why an - exact number is only given on that band). - -### W7 — Remediation engine — **done** - -- `RemediationAction` carries owner, segment, the change requests it would emit, expected effect, - trade-off and verification. An action with no changes is guidance, not a failure: that is the - normal and honest shape past the router, and `RemediationPlanner` produces it rather than - inventing a lever. -- `UseCaseProfiles`: competitive gaming, streaming and upload, calls and remote work. They weight - *different* objectives and say so — the streaming profile deliberately leaves on the receive - coalescing and large-send offloads the gaming profile switches off. A profile only proposes a - keyword the installed driver advertises, only a value it offers, and only for standardised NDIS - keywords: vendor keyword values are not standardised, so no profile can know what one means. -- `RemediationTargets`: bandwidth / max ping / max jitter. A target with nothing measured against - it is reported unmet with the reason, never quietly counted as met. -- Everything flows through `SettingTransactionService` unchanged — a test prepares a profile's own - change requests through the engine, so a profile that proposed something the engine would refuse - would fail the suite. -- Research corpus: four new registry-backed catalog entries, individually gated — `tcp.interface.mtu` - (the exact PMTUD black-hole workaround), `tcp.interface.netbios-options` (one interface, never a - blanket disable), and the two DWORD `Tasks\Games` MMCSS priorities. - -**Deferred with the reason.** The `Tasks\Games` string values -(`Scheduling Category`, `SFIO Priority`) need `SettingDefinition` to carry a non-numeric type. -Teredo, ISATAP and 6to4 have no per-component registry lever — only the blanket -`Tcpip6\Parameters\DisabledComponents`, which the architecture forbids. - -### W8 — Router integration — **guidance done, SSH transport deferred** - -- `RouterGuidance` emits `RouterInstruction`s, each a parameter, a value and the reason for that - value. The suite asserts all three on every instruction, so "check your QoS settings" cannot pass. -- SQM/CAKE for bufferbloat: shaped limits computed at 90% of the rate actually *measured* in each - direction, only for a direction that measured C or worse, plus qdisc, script and the link-layer - caveat. The verification step says what to do when the grade does not move, because a - variable-rate line needs more headroom than a fixed one. -- Wi-Fi channel and width, and the double-NAT way out. The channel handed to the router comes from - `WifiRadioAnalyzer.RecommendChannel`, the same call the report uses, so the two cannot drift. On - a tie the current channel wins — moving between two equally clear channels is churn. -- Each instruction carries its OpenWrt UCI path where one exists, so it can be typed as-is today and - written by the same value once the transport lands. Double NAT deliberately carries none: bridge - mode is on the ISP's device, not on OpenWrt. - -**Deferred with the reason.** The OpenWrt SSH transport needs an SSH client library — the first -third-party runtime dependency in the product — plus key handling and a credential policy. Under -the roadmap's own rule that anything touching a privilege boundary gets a separate security review, -that is its own increment rather than a tail of this one. Nothing else in W8 depends on it: the -guidance is complete and actionable without it. - -### W9 — Reporting, baseline, watchdog — **done** - -- `BaselineAnalyzer` compares recent runs against older ones over the existing history store. It - takes the median of each side, so one bad run in a week does not become the verdict, and it - requires both a percentage *and* an absolute move before calling anything significant — 2 ms to - 3 ms is 50% and means nothing. Runs with different parameters are refused rather than compared. -- Before/after report per applied fix: `DiagnosticReportExporter.SerializeComparisonHtml` renders - what was written next to what the identical re-run measured, reusing - `DiagnosticComparisonService`. When the two runs are not comparable it says so and shows no - metrics — an "improvement" between runs with different parameters is not an improvement. -- ISP evidence export already existed as the redacted HTML/JSON exporter; the before/after report - takes the same `redact` flag and blanks the adapter target with it. -- `Watchdog` judges a rolling window rather than single samples: one lost probe is not an outage, - and a user woken by every one of them stops reading the alerts. Alerts bracket the samples that - were actually bad, so "when did this start" is answered with a time earlier than the alert - itself. Bounded window per target and a bounded alert list, so it can run for hours behind - `NetworkMonitorService`. - -### W10 — TCP Optimizer parity — **done** - -SockTuner should be able to replace the SpeedGuide TCP Optimizer. That means parity of *coverage*, -deliberately not parity of *values*. - -- **Write path.** `CimGlobalSettingStore` writes `MSFT_NetTCPSetting` (per template) and - `MSFT_NetOffloadGlobalSetting`. The provider is the allowlist exactly as the driver is for NIC - keywords: the accepted values of an enumerated property come from the class's own `ValueMap` - qualifier in the live namespace, so the constraint is whatever this build implements rather than a - table carried in source. There is no free-form tier — a property advertising neither an - enumeration nor a documented range is not exposed. -- **Verified against the live provider:** 93 capabilities over five TCP templates plus the global - offload switches, all enumerated or ranged. The congestion providers on a current build run to - BBR2. A live test asserts every discovered current value fits the constraint declared for it — - it caught `DynamicPortRangeStartPort`, which ships at 1024 below a floor first written as 1025, - and would have made the property permanently unchangeable because the engine validates the - current value before planning. -- **Write ≠ effect.** Group policy and the template a connection is mapped to both outrank a local - write, so the store compares against `AutoTuningLevelEffective` afterwards and records the write - as ineffective when the stack did not move. Reading back the address only proves the first. -- **Registry additions:** `TcpTimedWaitDelay`, and the DNS client cache TTL caps. The writable - allowlist is now derived from the catalog instead of maintained beside it — the two had already - drifted, so `tcp.interface.mtu` could be planned and then refused at write time. -- **`InertSettingCatalog`.** What other tools still write that modern Windows does not read, each - with the reason and an honest confidence level: `TcpWindowSize` and `GlobalMaxTcpWindowSize` - (superseded by auto-tuning in Vista), `Tcp1323Opts`, TCP Chimney and NetDMA (removed from the - OS), `MaxUserPort` (superseded by the dynamic port range), `DefaultTTL`, `SackOpts=0`, - `MaxConnectionsPerServer`, `IRPStackSize`. Three more are marked Medium or Low confidence and - stay cautions until the capability archive confirms them. The suite asserts nothing writable - names one of these. Writing a value Windows stopped reading years ago produces a placebo the - user then credits for every later improvement, and the real cause never gets found. -- **`TcpTuningAdvisor` — the part a fixed preset cannot do.** A TCP connection's ceiling is - window ÷ round-trip time, so the auto-tuning level that costs nothing on a short fast path throws - most of a long one away. The level is therefore derived from the measured bandwidth-delay product - and the measured bufferbloat grade, in both directions: hold the window down when a download is - filling a bloated queue (stating the throughput it will cost), and *raise it back* when the - machine is throttling itself — the state a fixed optimizer preset leaves behind. No use-case - profile ships a global TCP value, and a test enforces that. - ---- - -## Research corpus integration - -Everything under `research/` is reference-only and is never executed. Its capabilities map to -SockTuner as follows. Blanket "disable everything" behaviour is deliberately **not** reproduced: -the architecture forbids blanket-disabling bindings, IPv6 and hidden adapters, and several of -these settings are actively harmful on some hardware. - -| Research source | Capability | Destination | Notes | -| --- | --- | --- | --- | -| `NetworkDiagnostics.ps1`, `gaming_net_diagnostic.ps1` | ping, jitter, traceroute, adapter facts | W1, W2 | Already largely native | -| `WinMTR` | continuous per-hop loss and latency | W1 | Native ICMP, no bundled binary | -| Bufferbloat projects | idle versus loaded latency | W5, W8 | Fix is router-side SQM | -| `GameNetAnalyzer` | jitter / burst / spike scoring, endpoint discovery | W5, W6 | tshark dependency dropped; native sockets and ETW instead | -| `Auto MTU.bat` | MTU probing | W6 | Native path-MTU already present | -| TCP global tweaks (`netsh int tcp ...`) | autotuning, ECN, timestamps, heuristics, RSS/RSC, initial RTO, templates | shipped | Written through `MSFT_NetTCPSetting` and `MSFT_NetOffloadGlobalSetting`; the provider's `ValueMap` is the allowlist | -| Offload scripts | checksum, LSO, RSC, RSS, USO, VMQ, RDMA | W7 | Already driver-advertised via CIM | -| MMCSS and `Tasks\Games` | throttling index, responsiveness, task priorities | shipped | Four entries; the two `Tasks\Games` string values need a non-numeric setting type | -| `TcpAckFrequency`, `TcpDelAckTicks`, `TCPNoDelay` | per-interface ACK behaviour | shipped | Experimental, typed confirmation | -| NIC power scripts | power saving, interrupt moderation | shipped | Driver-advertised | -| NetBT / NetBIOS, Teredo / ISATAP / 6to4 | legacy protocol disable | partly shipped | NetBIOS is per-interface and gated; Teredo/ISATAP/6to4 only have the blanket lever, which is forbidden | -| AFD, Dnscache, NDIS parameters | socket and resolver buffers | W7 | Needs documentation review before exposure | - -## Sequencing - -1. ~~**W1–W4** — diagnosis core and probe archive.~~ **Done.** -2. ~~**W5, W6** — active measurement and topology facts.~~ **Done.** -3. ~~**W7** — remediation engine and research-derived catalog growth.~~ **Done.** -4. ~~**W8** — router guidance.~~ **Done.** Optional OpenWrt SSH remains a separate increment. -5. ~~**W9** — baseline, watchdog, reporting.~~ **Done.** -6. ~~**W10** — global TCP and offload write path, and TCP Optimizer parity.~~ **Done.** - -Each workstream lands with its own tests and keeps the default suite host-independent. diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md deleted file mode 100644 index 730ceb6..0000000 --- a/docs/DEVELOPMENT.md +++ /dev/null @@ -1,76 +0,0 @@ -# Development - -## Requirements - -- Windows 10/11 x64 -- .NET 10 SDK -- No external networking tools are required - -## Safe local checks - -```powershell -dotnet restore SockTuner.sln -dotnet format SockTuner.sln --verify-no-changes -dotnet build SockTuner.sln -c Release --no-restore -dotnet test SockTuner.sln -c Release --no-build -``` - -The default tests are deterministic/in-memory and do not modify Windows network settings. Do not run material under `research/`. - -## Run the application - -```powershell -dotnet run --project src/SockTuner/SockTuner.csproj -``` - -The UI exposes read-only inventory and diagnostics, plus the **Tuning plan** tab: driver-advertised adapter properties filtered by intent preset (latency, bandwidth, power and wake, Wi-Fi radio, VLAN and identity), with preview, apply and exact rollback. Preview always reads through a read-only store; only an explicit apply elevates. - -## DPI validation - -The disposable Italian Windows 11 VM validates the live application at its Hyper-V display driver's native 100% scale. The virtual driver advertises no alternate scale offsets, so the same real WPF `App`/`MainWindow` visual tree is additionally rendered at 125%, 150%, and 200% pixel density for every tab. Evidence remains outside the repository under `C:\VmLab\Runs`; the VM is restored to `Clean-Base` afterward. - -## Mutation safety - -Live writes are enabled in the alpha. The `SOCKTUNER_ISOLATED_VM_MUTATIONS` environment gate has been retired; four independent controls replace it: - -1. **Alpha consent.** The first apply shows a blocking risk notice covering adapter restarts, connectivity loss, and recovery. Acceptance is stored in preferences as a versioned record (`WriteConsent.CurrentVersion`), so changing the risk text re-prompts. -2. **Elevation.** The UI stays unelevated. Applying launches the same executable as a short-lived elevated worker over a private named pipe and exchanges one typed JSON request. A dismissed UAC prompt is reported as a clean no-op. -3. **Per-setting gating.** Registry-backed catalog settings must appear in `WindowsRegistrySettingStore.WritableSettingIds`. NIC properties have no static allowlist: **the driver is the allowlist**. A NIC change is legal only if the CIM provider still advertises that keyword for that adapter and the value satisfies the driver's own `ValidRegistryValues` or min/max/step — re-read inside the elevated process immediately before writing, never trusted from the caller. -4. **Typed confirmation.** Any change that is `ChangeRisk.High` or `EvidenceLevel.Experimental` additionally requires typing `APPLY`. - -Every apply still runs `read → plan → snapshot → apply → read-back verify → audit`, refuses a stale plan, and rolls back in reverse order on failure. NIC writes go through `MSFT_NetAdapterAdvancedPropertySettingData`, so no registry path is ever composed from plan data; affected adapters are then restarted via `MSFT_NetAdapter.Restart()` and checked back to the link state they had beforehand. - -Default and CI tests never touch the host. Read-only checks against real drivers are opt-in: - -```powershell -$env:SOCKTUNER_LIVE_INVENTORY = '1'; dotnet test SockTuner.sln -c Release -``` - -## CI - -`.github/workflows/ci.yml` runs on pushes and pull requests to `main`: - -1. restore; -2. formatting verification; -3. Release build; -4. unit tests; -5. test-result upload. - -## Pre-releases - -**Pushing a semantic-version tag such as `v0.7.0-alpha.2` ships a release automatically** — treat tag pushes as the release action. `.github/workflows/release.yml` validates the tag, requires its commit to belong to `main`, builds and tests, publishes a self-contained `win-x64` single-file app (native libraries self-extract at runtime), creates a ZIP and SHA-256 file, and creates a GitHub pre-release. Re-running for an existing tag from the Actions tab (workflow dispatch) is also supported. - -Release safety controls: - -- the workflow only runs for the `PrimeBuild-pc/SockTuner` repository and only the repository owner can trigger the publishing jobs; -- the tag must match strict semver, belong to `main`, and is revalidated for immutability before publishing; -- signing secrets are repository secrets, never exposed to pull-request workflows (CI for PRs runs without secrets). - -Unsigned builds include `UNSIGNED-PREVIEW.txt` (SmartScreen warning + SHA-256 verification instructions). To sign the executable, configure these repository secrets: - -- `WINDOWS_CERTIFICATE`: Base64-encoded PFX; -- `WINDOWS_CERTIFICATE_PASSWORD`: PFX password. - -Dependabot pull requests are squash-merged automatically by `.github/workflows/dependabot-auto-merge.yml` once the required `build-test` check passes (the workflow uses `pull_request_target` because Dependabot-triggered `pull_request` runs get a read-only token; it never checks out PR code). - -Stable/public release policy remains blocked until signing, installer, update verification, and the release checklist are complete. diff --git a/docs/GITHUB.md b/docs/GITHUB.md index 71599f4..71bade1 100644 --- a/docs/GITHUB.md +++ b/docs/GITHUB.md @@ -45,7 +45,7 @@ wpf Use this near the top of the README until a safe public build exists: -> **Status: pre-alpha development. Read-only inventory and diagnostics are under construction; live network mutations remain disabled.** +> **Status: alpha development. Live changes are capability-gated, previewed, verified, audited, and reversible; use them only on a machine you can recover locally.** ## Public-launch checklist diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md deleted file mode 100644 index 6858686..0000000 --- a/docs/HANDOFF.md +++ /dev/null @@ -1,147 +0,0 @@ -# SockTuner — handoff rapido - -Aggiornato: **2026-09-26** -Workspace: `C:\Users\Lorenzo\Documents\Projects\SockTuner` -Branch osservato: `test/capability-archive-gate` -HEAD osservato: `df40eeae8711a4cb0fa9cb6c33b4b8b74d092e51` (`docs: archive Zenit research findings`) - -## Leggere prima di agire - -1. Leggere `AGENTS.md`: contiene i vincoli di sicurezza e il workflow obbligatorio. -2. Non eseguire script o binari sotto `research/`; quel materiale è solo riferimento statico. -3. Non effettuare mutazioni di rete sul computer di sviluppo. I test di scrittura usano fake/in-memory; - quelli Windows reali richiedono una VM usa-e-getta e opt-in esplicito. -4. Preservare le modifiche esistenti. Non usare reset/checkout distruttivi per “pulire” il working tree. - -## Stato del prodotto - -Il piano implementativo principale è sostanzialmente completo: - -- tutti i workstream W1–W10 di `docs/DELIVERY_PLAN.md` risultano completati; -- gli Step 1–6, 8 e 9 della roadmap sono completi; -- Step 7a è completo e Step 7b resta in alpha come attività continuativa di validazione hardware; -- Step 10 (private beta/1.0) dipende soprattutto da prove esterne, non da altro codice ordinario. - -Non c'è una feature applicativa lasciata a metà. La coda reale è: - -1. ampliare il corpus Step 7b quando arrivano probe da hardware reale; -2. chiudere Step 10 con certificato di firma, macchine Windows 10/11 reali, DPI e locale EN/IT, - screen reader, soak test e recovery drill in VM; -3. lasciare il trasporto OpenWrt SSH come incremento separato finché non sono definiti dipendenza, - gestione delle chiavi e review della superficie di sicurezza. - -Fonti autorevoli: `docs/ROADMAP.md` e `docs/DELIVERY_PLAN.md`. - -## Lavoro appena svolto: nuovo probe Realtek - -Sul Desktop erano presenti due JSON: - -- `socktuner-probe-20260915-064213.json` — utile direttamente alla capability matrix; -- `NeuroTune-HardwareReport-20260915-134216.json` — utile solo come corroborazione hardware. - -Il probe SockTuner è stato elaborato con lo strumento già esistente: - -```powershell -python tools\build-probe-archive.py 'C:\Users\Lorenzo\Desktop' -``` - -Risultato intenzionale: - -- aggiunto `alpha-tester-output/Realtek-2-5GbE-10.79.50.1003.json`; -- archiviato il report redatto originale in - `alpha-tester-output/reports/socktuner-probe-20260915-064213.json`; -- aggiornato `alpha-tester-output/INDEX.md` da 8 a 9 adattatori fisici e da 77 a 82 keyword; -- caratterizzate 33 proprietà NDIS e 33 capability strutturate per Realtek RTL8125, - driver `10.79.50.1003`, Windows `10.0.26200.0`. - -La copia del probe sul Desktop è stata eliminata **solo dopo** avere verificato che il suo SHA-256 -fosse identico alla copia nel progetto: - -```text -D47E5C28705261BDD049D0B9A302A7DC1D41BF23F6C1D81A3594FEEBEEF86722 -``` - -Il report NeuroTune non è stato copiato nel progetto e resta sul Desktop. Conferma la stessa NIC, -il driver, il PCI ID e il supporto MSI, oltre a una CPU Intel i5-10600K 6C/12T in un solo processor -group. Non contiene però vincoli sufficienti per aggiungere una nuova regolazione scrivibile alla -matrice, quindi non è stata inventata alcuna feature. - -## Incremento capability matrix completato - -Il gate dell'archivio ha rilevato cinque keyword standard pubblicizzate dal nuovo driver ma non -ancora caratterizzate. Il catalogo centrale ora classifica: - -- `*RSS` e `*NumRssQueues` come controlli di latenza/throughput a rischio medio; -- `*SelectiveSuspend` e `*SSIdleTimeout` come controlli di latenza/potenza a rischio medio; -- `*ModernStandbyWoLMagicPacket` come controllo wake/potenza a rischio basso. - -Le classificazioni sono coperte dai test e riportate nei record derivati dell'archivio. Il report -redatto originale resta invariato come provenienza. Oltre al nuovo record Realtek, l'entry Hyper-V -preesistente è stata allineata per le due keyword RSS che contiene. Il generatore preserva queste -classificazioni revisionate quando un report raw più vecchio riporta ancora `Unknown`; la modalità -read-only `python tools/build-probe-archive.py --check` verifica che la rigenerazione non produca diff. - -`git status` può mostrare altri JSON tracciati sotto `alpha-tester-output/` come modificati per solo -rumore di line ending. Non includerli alla cieca: `git diff --name-only` mostra le differenze di -contenuto reali. - -## Verifiche eseguite - -Dopo l'aggiunta del probe e la caratterizzazione delle nuove keyword: - -- `dotnet restore`: riuscito, progetti già aggiornati; -- `dotnet build --no-restore`: riuscito, 0 warning e 0 errori; -- `dotnet test --no-build`: 763 passati, 12 live test esclusi, 775 totali; -- `dotnet format --verify-no-changes`: riuscito; -- `python tools/build-probe-archive.py --check`: archivio rigenerabile senza diff; -- `git diff --check`: riuscito; -- entrambi i nuovi JSON sono stati parsati correttamente; -- nessun test Windows live o mutazione di rete è stato eseguito. - -## Analisi Zenit appena conclusa - -La nuova cartella `research/tools/Zenit/Zenit - Jackpot Latency Suite/` è stata confrontata -staticamente con le versioni precedenti. Non è stato eseguito nulla sotto `research/`. - -Il report completo è `docs/JACKPOTS_ZENIT_7.0_LATENCY_SUITE_DELTA.md`. Conclusione: - -- quasi tutto è già presente in SockTuner in forma più sicura, è fuori scope o non ha evidenza; -- non copiare preset RSS statici, “unlock” via registro, valori `Ndi\Params` inventati, reset - Winsock/IP, disabilitazioni massive dei binding o i verdetti deboli del verifier Ghidra; -- l'unico candidato futuro interessante è il controllo nativo della topologia RSS tramite - `MSFT_NetAdapterRssSettingData`. - -Quel candidato **non è una fase attiva** e non serve per chiudere la release corrente. Se verrà -richiesto, la versione minima sicura è: - -1. prima ampliare l'inventario read-only con indirection table, RSS processor array, numero di - interrupt, MSI/MSI-X; -2. poi introdurre un'unica impostazione composita tipizzata che snapshotta e ripristina l'intera - policy RSS di un adattatore preciso; -3. validare processor groups, topologia e limiti live, senza mappe CPU basate sul solo core count; -4. verificare apply e rollback in VM e rileggere anche la tabella di indirizzamento risultante. - -## Direzione architetturale da preservare - -- C#/.NET 10 LTS, WPF, x64-first, Windows 10/11. -- API native/CIM prima di tutto; nessuna dipendenza PowerShell a runtime e nessuna shell arbitraria. -- UI normalmente non elevata; worker elevato tipizzato e allowlisted per le scritture. -- Ogni setting scrivibile deve avere snapshot, validazione live, read-back, audit e rollback esatto. -- Le capability NIC derivano da ciò che il driver pubblicizza; proprietà assenti non si creano e - valori non pubblicizzati non si indovinano. -- Diagnosi, raccolta e remediation restano separati; la remediation propone modifiche e passa dal - transaction engine esistente. -- Preferire incrementi piccoli. Non ampliare lo scope solo perché una ricerca esterna elenca molti - tweak. - -## Avvio rapido per il prossimo agente - -```powershell -Get-Content AGENTS.md -Get-Content docs\HANDOFF.md -git status --short --untracked-files=all -``` - -Obiettivo successivo: continuare Step 7b solo quando arrivano probe da altro hardware reale, oppure -chiudere le prove esterne di Step 10. Non iniziare una riscrittura o implementare automaticamente -il candidato RSS composito. diff --git a/docs/JACKPOTS_ZENIT_4.0_DELTA.md b/docs/JACKPOTS_ZENIT_4.0_DELTA.md deleted file mode 100644 index ca654dc..0000000 --- a/docs/JACKPOTS_ZENIT_4.0_DELTA.md +++ /dev/null @@ -1,248 +0,0 @@ -# Reference notes: "Jackpot Hardware Tuner Zenit 4.0" — delta vs 3.0 - -> **Provenance and status.** Companion to [JACKPOTS_ZENIT_REFERENCE.md](JACKPOTS_ZENIT_REFERENCE.md) -> (the 3.0 notes). Same source family (Noverse/"Jackpot" IMOD tool, bundled `RW.exe` + -> WinRing0/inpoutx64 kernel drivers). Same rule applies: **nothing here is a verified -> recommendation and none of the code should be copied.** What's useful is the *list of -> new knobs/techniques* to cross-check against SockTuner's own design -> ([PRODUCT_SCOPE.md](PRODUCT_SCOPE.md), [ROADMAP.md](ROADMAP.md), -> [`SettingCatalog`](../src/SockTuner/Services/SettingCatalog.cs)), and the *measurement* -> idea, which is the one genuinely new capability. -> -> Files compared: `Jackpots Zenit 3.0/` vs `Jackpot Hardware Tuner Zenit 4.0/` -> (`IMOD-Test.py` 33.7 KB → 50.7 KB, `IMOD_Dashboard.py` 28.6 KB → 61.0 KB). -> -> **Next version:** [JACKPOTS_ZENIT_5.0_DELTA.md](JACKPOTS_ZENIT_5.0_DELTA.md) -> (5.0 adds no networking knobs — GPU tweaks, a junk cleaner, and a download launcher) -> · [JACKPOTS_ZENIT_5.3_DELTA.md](JACKPOTS_ZENIT_5.3_DELTA.md) (5.3 — registry-tweak -> verification method). - -## TL;DR — what changed and what (if anything) is worth taking - -| # | 4.0 change | New vs 3.0? | Useful to SockTuner? | -|---|---|---|---| -| 1 | **Dynamic PnP hardware scan** (`Get-PnpDevice` + `DEVPKEY_Device_LocationInfo` → BDF at scan time) | New | **Yes, as a pattern** — proper device discovery, not hard-coded addressing | -| 2 | **Dynamic MTU auto-detection** (ping DF-bit binary probe, +28) | New | **Yes** — documented, safe, a real "detect optimal" feature idea | -| 3 | **DPC/ISR latency measurement** (deferred xperf pipeline, weighted latency per module) | New | **Yes — the one interesting new idea**: before/after *quantification* | -| 4 | **State reconciliation** from last-run log (per-device ACTIVE/LOCKED checklist) | New | Concept yes, implementation no (parses stdout, not real state) | -| 5 | **MSI-mode forcing** (`MSISupported=1`, drop `MessageNumberLimit`) | New | Maybe — documented registry mechanism, legit for NIC | -| 6 | **Physical-NIC detection via `Characteristics` bit 0x4** (`NCF_PHYSICAL_ADAPTER`) | New | Minor — better than pure name regex | -| 7 | **~15 extra documented TCP/IP knobs** (PMTU, ServiceProvider priorities, AFD, DNS negcache…) | New values | Cross-check catalog | -| 8 | **Native WinRing0 DLL C-bindings + hybrid runner + verify-read-back** | Rewrite | Architecture note only; verify-read-back worth mirroring | -| 9 | Driver-blocklist disable, MMIO ITR/EEE pokes, MSR pokes, ~90 unchecked NDIS props, BDF cached into generated .bat | **Unchanged** | Still all the §0/§3/§8 anti-patterns. Do not adopt. | - ---- - -## 1. Dynamic PnP hardware scan (`IMOD_Dashboard.py::safe_scan`) — the "hardware scanning" you asked about - -3.0 hard-coded BDF addresses. 4.0 discovers devices at scan time with one PowerShell pass: - -```powershell -Get-PnpDevice -PresentOnly | Where-Object { $_.Class -eq 'USB' -and $_.FriendlyName -match 'xHCI|eXtensible' } ... -Get-PnpDevice -Class 'Display' -PresentOnly ... -Get-PnpDevice -Class 'System' -PresentOnly | Where-Object { $_.FriendlyName -match 'PCI Express Root|Host Bridge' } ... -Get-PnpDevice -Class 'Net' -PresentOnly | Where-Object { $_.FriendlyName -match 'Ethernet|Network|Gigabit|2.5G|Gaming' -and $_.FriendlyName -notmatch 'Virtual|TAP|VPN|Bluetooth' } ... -Get-PnpDevice -Class 'SCSIAdapter' -PresentOnly | Where-Object { $_.FriendlyName -match 'NVMe|Express' } ... -``` - -For each device it reads `DEVPKEY_Device_LocationInfo` (a string like `"PCI bus 8, device 0, function 0"`), -regexes the three integers out, and formats them into a `bus:dev.func` BDF. It also drops integrated -GPUs (`intel(r) uhd/iris`, `radeon graphics`) to `SKIP` automatically. - -**Why this matters for SockTuner:** it's the correct answer to the 3.0 anti-pattern §8 -("fixed device addressing"). Resolving the NIC *at run time* from a stable OS device -property is exactly what SockTuner already wants for adapter targeting. The specific -mechanism — `Get-PnpDevice -Class 'Net' -PresentOnly` filtered by -`Virtual|TAP|VPN|Bluetooth`, plus `DEVPKEY_Device_LocationInfo` — is a clean, documented -CIM/PnP path and maps to `MSFT_PnpDevice` / `Get-PnpDeviceProperty` in WMI, reachable from -.NET via `System.Management` (already a SockTuner dependency). - -**Caveat — still only half-fixed.** `save_startup()` then bakes the resolved BDF strings -into a generated `.bat` and registers a `schtasks ONLOGON` task. So the *scan* is dynamic -but the *saved startup profile* re-freezes the topological address — a slot/BIOS change -still mis-targets on next boot. SockTuner's design (resolve at apply time, every time) -remains the stricter, correct position; 4.0 only moved the freeze one step later. - -## 2. Dynamic MTU auto-detection (inside the "Zenot" PowerShell block) - -Genuinely new and genuinely safe — worth noting as a feature idea: - -```powershell -$bestP = 0 -for ($p = 1472; $p -ge 1400; $p--) { - ping.exe 1.1.1.1 -f -n 1 -l $p -w 1000 | Out-Null # -f = don't-fragment - if ($LASTEXITCODE -eq 0) { $bestP = $p; break } -} -if ($bestP -gt 0) { - $mtu = $bestP + 28 # + 20 IP + 8 ICMP headers - netsh interface ipv4 set subinterface "" mtu=$mtu store=persistent -} -``` - -Probe the largest ICMP payload that traverses the path without fragmenting, add the 28-byte -header, and that's the path MTU. It's a linear scan (1472→1400) rather than a binary search, -and it hard-codes `1.1.1.1` as the probe target, but the *technique* is sound and 100% user-mode. -A "Detect optimal MTU" helper is a plausible SockTuner feature — do it with `SendARP`/IP -Helper or a raw ICMP `Ping` with `DontFragment` in .NET instead of shelling `ping.exe`, and -binary-search the range. Pair with the existing interface-metric knob (4.0 also forces -`InterfaceMetric 1` via `Set-NetIPInterface`). - -## 3. DPC/ISR latency measurement — the deferred xperf pipeline (`IMOD-Test.py::run_xperf_deferred_pipeline`) - -This is the **one new capability class** 3.0 didn't have: it *measures* instead of only -writing. The tool ships the Windows Performance Toolkit (`xperf/xperf.exe`) and runs: - -1. GUI closes itself first ("0% GUI DPC overhead"), `time.sleep(60)` for idle stabilization. -2. `xperf -on PROC_THREAD+LOADER+DPC+INTERRUPT`, trace 20 s, `xperf -d out.etl`. -3. `xperf -i out.etl -o out.txt -a dpcisr` → parse the DPC/ISR-by-module report. -4. Aggregates per driver module, then computes **weighted latency (µs)** and an **effective - impact (%)** for DPC, ISR, and total; writes a summary, drops a `xperf_ready.flag`, and - relaunches the GUI, which detects the flag and pops the report. - -**Why it's interesting for SockTuner:** every tweak in this whole family is asserted, never -demonstrated. A measurement path — "here's DPC/ISR latency attributable to the NIC driver -before vs after" — is what would let SockTuner make *evidence-based* claims instead of -cargo-culting registry values. This fits the project's stated engineering position -(README "prefer verifiable"). The xperf `-a dpcisr` action and the `PROC_THREAD+LOADER+DPC+INTERRUPT` -kernel group are the documented WPT surface; a future SockTuner "benchmark / verify" step -could wrap WPR/WPA or `xperf` the same way (redistribution licensing to be checked). The -weighting math in the script is home-grown and unvalidated — take the *idea* (per-module -DPC/ISR before/after), not their formula. - -## 4. State reconciliation from log (`parse_log_checklist`) - -On each scan the dashboard re-reads `startup_log.txt` from the last apply run and rebuilds a -per-device status: it string-matches `"SUCCESS"`, `"already set"`, `"hardware locked"`, -`"ASPM ... Purged"`, `"USB Interrupter ... set to"` etc., and tags each BDF `ACTIVE`, -`ACTIVE (512B)`, or `LOCKED ()`. The table then shows which devices are currently -optimized and which hit a hardware ceiling. - -Concept is right (show applied vs. not, surface hardware-locked limits) and aligns with -SockTuner's planned Step 5 dry-run/rollback/audit. Implementation is the wrong way to do it — -it parses its own console stdout rather than reading actual current registry/register state. -SockTuner should snapshot the real prior value and re-read the real current value (it already -plans to). Keep the **UX idea**: a per-setting badge of `applied / default / locked-at-max`. - -## 5. MSI-mode forcing (new, documented registry mechanism) - -New in the Zenot block — for each physical NIC (and GPU, and `USBXHCI` controllers) it does: - -``` -HKLM\...\Enum\PCI\\Device Parameters\Interrupt Management\MessageSignaledInterruptProperties - MSISupported (DWord) = 1 - (delete MessageNumberLimit) -``` - -This is the standard, documented "force MSI/MSI-X interrupts" tweak (same thing MSI-mode -utilities do). Unlike the MMIO ITR pokes in §3 of the 3.0 notes, it's a supported registry -location. If SockTuner ever expands past NDIS advanced properties, `MSISupported` for the NIC -is a legitimately documentable knob (with the usual "driver/device must support it, and it's -per-instance under Enum\PCI, resolved dynamically" caveats). Note it targets `Enum\PCI\...` -device-instance keys, so it needs the same dynamic-resolution discipline as §1. - -## 6. Physical-NIC detection via Characteristics bit (improvement over 3.0) - -3.0 gated purely on a driver-description regex. 4.0 first checks the NDIS `Characteristics` -value for bit `0x4` (`NCF_PHYSICAL_ADAPTER`) and only falls back to the vendor regex: - -```powershell -$isPhysical = ([int]$characteristics -band 0x4) -eq 0x4 -$isEthernetVendor = $driverDesc -match 'Intel|Realtek|Killer|Aquantia|Broadcom' -if ($isPhysical -or $isEthernetVendor) { ... } -``` - -Closer to SockTuner's "ask what it is, don't string-match" principle. Still an `-or` with the -regex, so a mislabeled vendor string can still pull in a non-physical adapter — but the -`NCF_PHYSICAL_ADAPTER` bit is the right primary signal and worth knowing for -`WindowsNdisInventory` adapter classification. - -## 7. New documented TCP/IP knobs to cross-check against the catalog - -4.0 adds these to the registry block (all documented Windows parameters; **values unvetted**, -listed only so nothing is missed in `WindowsTcpSettingInventory` / `SettingCatalog`): - -``` -Tcpip\Parameters: - EnablePMTUDiscovery=1, EnablePMTUBHDetect=1, TcpMaxDataRetransmissions=2, - MaxUserPort=65534, LoopbackLargeMtu=0 -Tcpip6\Parameters: - LoopbackLargeMtu=0, DisabledComponents=0x20 -AFD\Parameters: - FastSendDatagramThreshold=1500 -Tcpip\ServiceProvider: - LocalPriority=4, HostsPriority=5, DnsPriority=6, NetbtPriority=7 -Dnscache\Parameters: - NegativeCacheTime=0, NegativeSOACacheTime=0, NetFailureCacheTime=0 -``` - -Plus native cmdlets instead of registry for offload globals — worth preferring over `netsh`: - -``` -Set-NetOffloadGlobalSetting -ReceiveSegmentCoalescing Enabled -Set-NetOffloadGlobalSetting -PacketCoalescingFilter Disabled -Set-NetOffloadGlobalSetting -UdpReceiveOffload Disabled -Set-NetIPInterface -InterfaceAlias -AutomaticMetric Disabled -InterfaceMetric 1 -``` - -(These map to `MSFT_NetOffloadGlobalSetting` / `MSFT_NetIPInterface` WMI classes — a native -P/Invoke/`System.Management` path, consistent with the project's "no shell-outs" goal.) -`DisabledComponents=0x20` is the documented "prefer IPv4 over IPv6" bit — behavioural, flag it -as opinionated. The `ServiceProvider` priority quartet is documented but obscure; verify before -cataloguing. - -## 8. Architecture rewrite (note only — do not adopt) - -3.0 shelled out to `chiptool.exe`/`RW.exe`. 4.0 rewrote the hardware layer: - -- **`NativeKernelRunner`** — loads `WinRing0x64.dll` directly (`InitializeOls`, - `ReadPciConfig{Byte,Word,Dword}`, `WritePciConfigWord`, `Wrmsr`) and `inpoutx64.dll` - (`MapPhysToLin`/`UnmapPhysicalMemory`) for MMIO — no more process shell-out. -- **`RwRunner`** — `Rw.exe` fallback (skips MSR writes: `"BSoD-Schutz: MSR-Write … übersprungen"`). -- **`SmartHardwareRunner`** — hybrid: tries RW first, falls back to native per-op, each wrapped - in try/except so one failing read doesn't abort the batch. -- **`resolve_mmio_base`** — walks BARs `0x10..0x24`, skips I/O-space BARs, handles 64-bit BARs - (`bar & 0x4` → read the high dword) before using the base. Cleaner than 3.0. -- **verify-read-back** — every write is followed by a read to confirm, and MRRS detects - "hardware locked at max supported limit". **This pattern is worth mirroring** in SockTuner's - apply step (write → re-read → report actual, surface silently-clamped values), independent of - the risky transport it rides on here. - -Still built on WinRing0/inpoutx64 (BYOVD-class drivers). Architecture note only. - -## 9. Unchanged anti-patterns — same warnings as the 3.0 notes still apply - -All of these carried over verbatim; nothing was fixed: - -- **§0 driver-blocklist disable is still there** — `apply_driver_blocklist_tweak()` sets - `HKLM\SYSTEM\CurrentControlSet\Control\CI\Config\VulnerableDriverBlocklistEnable = 0`, and - 4.0 now calls it **unconditionally at the top of `get_hardware_runner()`**, i.e. on every - hardware run, still with no UI disclosure. Same hard "never do this" from the 3.0 notes §0. -- **MMIO ITR/EEE pokes unchanged** (Intel `+0x00C4`/`+0x0E00`, Realtek `+0x00EC`/`+0x00D4`, - HD-Audio INTCTL `+0x08` bit31) — still undocumented offsets written behind the driver's back. -- **MSR pokes unchanged/expanded** — `IA32_ENERGY_PERF_BIAS` (0x1B0) and AMD - `0xC0010296` (undocumented "Data Fabric C-State Lock"), both forced to 0. Out of SockTuner's - networking scope regardless. -- **~90 NDIS properties still written unconditionally** by name, gated only by the - vendor/`Characteristics` `-or`, never checked against what the driver advertises; still - includes the guessed Realtek `HwOption*` bitmasks. SockTuner's "driver-advertised only" - design is still the right counter-position. -- **BDF still cached into a generated `.bat` + `schtasks ONLOGON`** (see §1 caveat). -- **Aggressive defaults** — the shipped `IMOD_Profile.bat` runs `--pcie-mrrs 5` (4096 B MRRS) - across GPU/NVMe/NIC and `--nic-imod --msr-epb`. Values to treat as "observed, not endorsed". - ---- - -### Net takeaways for SockTuner (future, not now) - -1. **Adopt the discovery pattern, not the code:** dynamic NIC resolution via - `Get-PnpDevice`/`DEVPKEY_Device_LocationInfo` (WMI `MSFT_PnpDevice`) instead of any cached - address — validates the design already in scope. -2. **Consider a "Detect optimal MTU" helper** (native ICMP DontFragment binary-search, not - `ping.exe`), paired with the interface-metric knob. -3. **The measurement idea is the real prize:** a before/after DPC/ISR (or simpler latency) - benchmark would let SockTuner *prove* effect instead of asserting it. Wrap WPT/`xperf -a - dpcisr` (check redistribution) — take the concept, not their weighting math. -4. **Mirror verify-read-back** in the apply path and surface hardware-clamped/locked values. -5. **Catalog cross-check** the §7 knobs and `MSISupported`; keep prefering native - `Set-Net*`/`System.Management` over `netsh`. -6. Everything in §9 stays on the "recognize the symptom, reject the method" list. diff --git a/docs/JACKPOTS_ZENIT_5.0_DELTA.md b/docs/JACKPOTS_ZENIT_5.0_DELTA.md deleted file mode 100644 index 5e7d46e..0000000 --- a/docs/JACKPOTS_ZENIT_5.0_DELTA.md +++ /dev/null @@ -1,201 +0,0 @@ -# Reference notes: "Jackpot's Hardware Register Engine v7.0" (Zenit 5.0) — delta vs 4.0 - -> **Provenance and status.** Third in the series after -> [JACKPOTS_ZENIT_REFERENCE.md](JACKPOTS_ZENIT_REFERENCE.md) (3.0) and -> [JACKPOTS_ZENIT_4.0_DELTA.md](JACKPOTS_ZENIT_4.0_DELTA.md). Same source family -> (Noverse/"Jackpot" IMOD tool, bundled `RW.exe` + WinRing0/inpoutx64 kernel -> drivers). **Same rule: nothing here is a verified recommendation and none of the -> code should be copied.** The value is the *list of new knobs/techniques* to -> cross-check against SockTuner's own design -> ([PRODUCT_SCOPE.md](PRODUCT_SCOPE.md), [ROADMAP.md](ROADMAP.md), -> [`SettingCatalog`](../src/SockTuner/Services/SettingCatalog.cs)). -> -> Folders compared: `Jackpot Hardware Tuner Zenit 4.0/` vs `Zenit_5.0/Zenit/`. -> Byte-level diff: the delta is almost entirely in **`IMOD_Dashboard.py`** -> (61.0 KB → 83.9 KB, +437 lines). Every other shared file is byte-identical -> (`IMOD_Cleaner.py`, `dpc-isr.vbs`, `gpu/`, `RW/`, `chiptool/`, `xperf/`, -> `power/`, `spowers/`, the `.pow`/`.nip` bundles). `Start_Hardware_Engine.bat` -> was renamed to `Click_to_Start.bat` (identical content). - -## TL;DR — what changed and what (if anything) is worth taking - -| # | 5.0 change | New vs 4.0? | Useful to SockTuner? | -|---|---|---|---| -| 1 | **Native registry helpers replace shelled-out `.bat`** for GPU/system toggles (`winreg` writes, not `subprocess` to a generated batch) | New | **Yes, as validation only** — confirms SockTuner's own native-registry stance; no new *network* knob | -| 2 | **NVIDIA ECC / HDCP disable via display-class registry keys** (`RMNoECCFuseCheck`, `RMHdcpKeyglobZero`, + `nvidia-smi -e`) | New | No — GPU, out of scope. Note the class-key discovery pattern only | -| 3 | **HAGS toggle** (`GraphicsDrivers\HwSchMode` = 2/1) | New | No — GPU, out of scope; but it's the "one DWORD, documented, reboot-gated" shape SockTuner already uses | -| 4 | **"Deep Cleaner"** background `QThread` — purges Temp/Prefetch/browser+Discord caches/WER/minidumps, `ipconfig /flushdns`, `wevtutil cl` on every log, deletes RunMRU/TypedPaths | New | **No — reject.** Destructive junk-cleaner well outside a NIC tuner. Only the async-worker+log-signal *pattern* is unremarkable/already-known | -| 5 | **"Take Ownership" Explorer context-menu** installer (writes `HKCR\*\shell` + `Directory\shell`) | New | No — reject; unrelated, and a persistent shell modification | -| 6 | **"Software Hub"** page: 53 hard-coded vendor download URLs opened in a browser | New | **No — reject.** Stale/unpinned installer URLs are a supply-chain smell; nothing to take | -| 7 | **`--clean-system` flag** threaded into the generated startup `.bat` | New (partial) | No — and see §7, the flag is dead on the launcher side | -| 8 | Theme unification (purple `#7C4DFF` → blue `#00B0FF`), button-variant cleanup, Noverse credits/links stripped | Cosmetic | No | -| 9 | **`IMOD-Test.py` shipped truncated/corrupt** (ends mid-statement at line 916; `parse_args`/`main`/CLI entrypoint gone) | Regression | No — quality/provenance signal, see §8 | -| — | All 3.0/4.0 hardware-poke anti-patterns (RW.exe MMIO/MSR pokes, ~90 unchecked NDIS props, BDF baked into `.bat`, driver blocklist) | **Unchanged** | Still all the §0/§3/§8 anti-patterns. Do not adopt | - -**Bottom line for SockTuner: nothing new worth adopting.** 5.0 is feature-creep -sideways into GPU tweaks, a system junk-cleaner, a context-menu hack, and a -software-installer launcher — none of it networking. The single positive signal -is architectural (§1): the new toggles are written with native `winreg` calls -instead of spawning a batch file, which is the direction SockTuner already took. - ---- - -## 1. Native registry helpers instead of generated `.bat` — the one architectural improvement - -4.0 (and earlier) executed system changes by writing a `.bat` and shelling out -to it. 5.0 adds a block of module-level helpers in `IMOD_Dashboard.py` that call -`winreg` directly and return `(success: bool, message: str)`: - -```python -def set_hags(enable: bool): - k = winreg.OpenKey(HKLM, r"SYSTEM\CurrentControlSet\Control\GraphicsDrivers", 0, KEY_SET_VALUE) - winreg.SetValueEx(k, "HwSchMode", 0, winreg.REG_DWORD, 2 if enable else 1) - winreg.CloseKey(k) - return True, "... (Reboot required)" -``` - -wired to the UI through a small dispatcher: - -```python -def handle_native_toggle(self, func, *args): - success, msg = func(*args_without_title) - self.log(f"{title}: {msg}") - QMessageBox.information/critical(self, ...) -``` - -**Why it matters for SockTuner:** this is Zenit belatedly arriving at the pattern -SockTuner started with — a typed apply that touches the registry in-process, -returns a structured result, and surfaces success/failure to the UI, instead of -generating and running a script. It's confirmation of the design choice, not a -new capability. SockTuner's C# equivalents (`WindowsNdisInventory`, the live -write path — the driver is the allowlist) are already stricter: they read back -and they don't persist a frozen artifact. **Take: nothing to import; note that -even the reference tool is moving toward in-process registry writes.** - -**Caveat.** The `(success, message)` helpers still don't verify-read-back after -the write (they trust `SetValueEx` returning), and several swallow every -exception into a string. SockTuner's read-after-write remains the stronger form. - -## 2. NVIDIA ECC / HDCP disable (out of scope — pattern note only) - -New helpers hunt the NVIDIA display adapter by walking -`...\Control\Class\{4d36e968-...}\0000..0009` and matching -`ProviderName` containing `NVIDIA`, then write: - -- ECC off: `RMNoECCFuseCheck=1` plus a batch of `RMEnable*ECC=0` keys, and - `nvidia-smi -e 0`. -- HDCP off: `RMHdcpKeyglobZero=1`, `RmDisableHdcp22=1`. - -These are GPU-latency-theatre knobs (disabling error-checking / display copy -protection for "gaming performance"), entirely outside a NIC tuner. The **only** -transferable detail is the *class-key discovery loop* — iterate the `{class-GUID}` -subkeys and match a stable property — which is the same shape SockTuner already -uses to resolve the NIC subkey under `{4d36e972-...}` in -[`WindowsNdisInventory`](../src/SockTuner/Services/WindowsNdisInventory.cs) -(matching on `NetCfgInstanceId`). Nothing new there. **Reject the knobs.** - -## 3. HAGS toggle (out of scope, but the "right shape" for a knob) - -`GraphicsDrivers\HwSchMode` = `2` (enabled) / `1` (disabled), reboot-gated, -single `REG_DWORD`, documented by Microsoft. GPU-side, so out of SockTuner's -networking scope — noted only because it's the clean archetype SockTuner already -follows: one documented value, clear revert, reboot requirement stated to the -user. No action. - -## 4. "Deep Cleaner" — reject - -New `CleanerWorker(QThread)` that, on a button or on startup (if the new -checkbox is set), deletes the contents of ~18 directories (`%TEMP%`, -`Windows\Temp`, `Prefetch`, `SoftwareDistribution\Download`, `Recent` + -Jump-List `AutomaticDestinations`/`CustomDestinations`, INetCache, History, -Edge/Chrome `Cache`, Discord `Cache`/`Code Cache`, WER `ReportArchive`/ -`ReportQueue`, `Minidump`), then `ipconfig /flushdns`, deletes the `RunMRU` and -`TypedPaths` registry keys, and loops `wevtutil cl` over **every** event log -from `wevtutil el`. - -This is a privacy/junk cleaner bolted onto a hardware tuner. It's destructive -(wiping Prefetch hurts cold-start times it claims to help; clearing all event -logs destroys diagnostic history; nuking `SoftwareDistribution\Download` can -disrupt pending Windows Update state). **Nothing to take.** The one -network-adjacent line, `ipconfig /flushdns`, is a trivial documented command -SockTuner can offer on its own terms if ever wanted — not a reason to look here. - -The `QThread` + `log_signal`/`finished_signal` structure is ordinary Qt worker -plumbing; SockTuner's WPF stack has the equivalent already. No pattern debt paid. - -## 5. "Take Ownership" context menu — reject - -Writes a `HKCR\*\shell\TakeOwnership` (+ `Directory\shell\...`) entry whose -command runs `takeown /f … && icacls … /grant *S-1-3-4:F` elevated. Persistent -shell modification, unrelated to networking, and a standing privilege-granting -menu item. Recognise it, reject it. - -## 6. "Software Hub" — reject (supply-chain smell) - -A new page renders 53 buttons across five sections (Gaming launchers, -Multimedia, Tools, Browsers, Dev SDKs); each opens a **hard-coded vendor URL** in -the default browser (`webbrowser.open`). Many are direct, unpinned installer -links (specific `.exe`/`.msi` versions, some CDN/redirector URLs, some third-party -"UNLOCKED"/modded builds hosted on random GitHub forks). - -For SockTuner this is a clear **anti-pattern**: shipping a curated list of -version-pinned download URLs is a maintenance and supply-chain liability (links -rot; a hijacked host serves malware behind a trusted button). It reinforces -SockTuner's existing "no bundled third-party binaries, no download launcher" -position. **Take nothing.** - -## 7. `--clean-system` flag is dead on arrival - -The dashboard now appends `--clean-system` to the generated startup `.bat` when -the new "Execute Deep Cleaner on Startup" checkbox is set, and reads it back to -restore checkbox state. But the **worker that actually parses that flag lives in -`IMOD-Test.py`, which 5.0 ships truncated** (§8) — its `parse_args`/`main` are -gone. So the startup batch would pass an argument the target script can no longer -handle. Even setting aside the corruption, wiring an on-boot destructive cleaner -into a `schtasks ONLOGON` task is exactly the kind of persistence + side-effect -SockTuner deliberately avoids. Ignore. - -## 8. `IMOD-Test.py` shipped broken — provenance/quality signal - -The 5.0 `IMOD-Test.py` is a **truncated copy**: it ends mid-statement at line 916 -(`print(f"[!]` with no closing quote — `SyntaxError: unterminated string -literal`), and the entire tail from 4.0 is missing: `parse_args`, `main`, and the -`if __name__ == "__main__"` entrypoint. The header was rebranded -(Noverse → "Jackpot's Hardware Register Engine") and an unused `glob` import -added, but the file cannot execute. The bundled `startup_log.txt` (paths under -`C:\Users\harald\Desktop\Jackpot Hardware Tuner PAID TOOL\`) and `crash_log.txt` -are leftovers from the author's own machine. - -**Relevance to SockTuner:** none technically, but it's a useful reminder about -the corpus — these are hand-assembled, sometimes-broken release folders sold as a -"PAID TOOL", not a maintained codebase. Treat every extracted value/mechanism as -*a lead to verify against Microsoft/vendor docs*, never as a working reference. - -## 9. Not new in 5.0 (already present in 4.0) - -To avoid re-mining: `power/` (USB selective-suspend + `PnPCapabilities=24` + -`MSPower_DeviceEnable` power-management-off + `powercfg -DeviceDisableWake`), -`spowers/` (Sordum Switch-Power-Scheme), and the whole `xperf/` DPC/ISR tracing -tree all already shipped in 4.0 and are byte-identical here. The -`PnPCapabilities=24` NIC power lever is already documented as **UNSAFE** in -[JACKPOTS_ZENIT_NDIS_CANDIDATES.md](JACKPOTS_ZENIT_NDIS_CANDIDATES.md#c-latency-tweaks-flagged-unsafe); -the DPC/ISR measurement idea is covered in the -[4.0 delta §3](JACKPOTS_ZENIT_4.0_DELTA.md). No change in 5.0. - ---- - -## Net takeaways for SockTuner (future, not now) - -1. **No new networking capability.** 5.0 adds zero NIC/TCP/NDIS knobs. Everything - new is GPU tweaks, a junk cleaner, a context-menu hack, and a software-download - launcher — all out of scope. -2. **Architectural confirmation only.** The move to native `winreg` toggles (§1) - validates SockTuner's in-process registry approach; SockTuner's read-back and - no-frozen-artifact stance stays stricter. Nothing to import. -3. **Explicit rejects** to keep on record: the Deep Cleaner (§4), Take Ownership - (§5), and the 53-URL Software Hub (§6) are anti-patterns that reinforce - SockTuner's "no bundled binaries, no destructive system-wide cleaners, no - download launcher" boundaries. -4. **Corpus quality caveat** (§8): this release ships a syntactically broken core - script. Continue treating extracted mechanisms as leads to verify, not as - working references. diff --git a/docs/JACKPOTS_ZENIT_5.3_DELTA.md b/docs/JACKPOTS_ZENIT_5.3_DELTA.md deleted file mode 100644 index 96406bf..0000000 --- a/docs/JACKPOTS_ZENIT_5.3_DELTA.md +++ /dev/null @@ -1,267 +0,0 @@ -# Reference notes: Zenit 5.3 — delta vs 5.0, and the `WinTweakVerifier` methodology - -> **Provenance and status.** Fourth in the series, after -> [JACKPOTS_ZENIT_REFERENCE.md](JACKPOTS_ZENIT_REFERENCE.md) (3.0), -> [JACKPOTS_ZENIT_4.0_DELTA.md](JACKPOTS_ZENIT_4.0_DELTA.md) and -> [JACKPOTS_ZENIT_5.0_DELTA.md](JACKPOTS_ZENIT_5.0_DELTA.md). Same source family -> ("Jackpot" IMOD tool, bundled `RW.exe` + WinRing0/inpoutx64 kernel drivers). -> **Same rule: nothing here is a verified recommendation and none of the code -> should be copied.** -> -> Folders compared: `Zenit_5.0/Zenit/` vs `Zenit - 5.3/Zenit - 5.2/` (the 5.3 -> archive contains a folder still named 5.2). `IMOD_Dashboard.py` 83.9 KB → -> 180.9 KB, `IMOD-Test.py` 47.2 KB → 28.2 KB. New folder: `WinTweakVerifier/`. -> -> **Unlike 4.0 and 5.0, this release contains something genuinely useful.** - -## TL;DR - -| # | 5.3 change | Useful to SockTuner? | -|---|---|---| -| 1 | **`WinTweakVerifier` — a placebo detector for registry tweaks.** Scans System32/SysWOW64 binaries for a registry value name, then uses PE analysis (imports, string VAs, `.text` xrefs, `RTL_QUERY_REGISTRY_TABLE` tracing) to classify each tweak GREEN / CYAN / YELLOW / RED | **YES — the single most valuable thing in the whole Zenit corpus.** Adopt the *method* as an offline research gate for the catalog; do not adopt the code or trust its verdicts unverified | -| 2 | **A 42-tweak verdict table**, incl. 15 marked outright placebo, and hard evidence naming `tcpipreg.sys` as the consumer of `TcpAckFrequency` / `Tcp1323Opts` | **Yes — direct cross-check data** for `SettingCatalog`. See §2 | -| 3 | **"Apply ONLY Verified Tweaks" button** — a `verified_targets.json` sidecar gates what gets written | **Yes, as a product principle** (evidence-gated apply). SockTuner already does this per-adapter via the driver; this extends the idea to global values | -| 4 | PCIe capability-list **walking** (`cap_ptr` chain from offset `0x34`, looking for cap ID `0x10`) replaces hard-coded register offsets, with verify-read-back on MRRS | Minor — confirms the "discover, don't hard-code" and "read back" principles SockTuner already applies | -| 5 | NDIS list trimmed ~90 → **44 properties**, offloads flipped from *disabled* to *enabled* (`3`), `*JumboPacket = 1510` | Cross-check only — and the whole block is now **orphaned dead code** (§6) | -| 6 | Five new CLI flags (`--pcie-mps`, `--pcie-ltr-clkreq`, `--usb-u0`, `--nvme-apst`, `--msr-cstate`); **four are dead** — parsed, never implemented | No — quality signal (§7) | -| 7 | `MainWindow` class body **duplicated (partly triplicated)**; ~1,300 lines are unreachable dead code — this is the entire 84 KB → 181 KB growth | No — quality signal (§8) | -| — | RW.exe/WinRing0 MMIO+MSR pokes, driver blocklist, BDF baked into `.bat` | **Unchanged.** Still the §0/§3/§8 anti-patterns. Do not adopt | - ---- - -## 1. `WinTweakVerifier` — the methodology worth stealing - -`WinTweakVerifier/win_tweak_verifier.py` (19 KB, `pefile`-based) answers a question -SockTuner genuinely needs answered: **does this registry value actually exist in -Windows code, and is anything reading it?** - -This matters because global registry knobs have no enumeration API. Unlike NDIS -keywords — where the driver advertises what it supports, so "the driver is the -allowlist" works — you can write *any* name under `Tcpip\Parameters` and Windows -will silently ignore it. That is exactly the niche where placebo tweaks breed, -and it is exactly the class of settings SockTuner carries outside its NDIS surface. - -### The pipeline - -1. **Parse a `.reg` file** → `(key_path, value_name, type, hex, decimal)` tuples. - Value names become the search terms. -2. **Fast parallel pre-scan** (`ProcessPoolExecutor`, one task per file) over every - `.dll`/`.exe`/`.sys` under `C:\Windows\System32` and `SysWOW64` — recursive, so - `System32\drivers\` and `DriverStore\FileRepository\` are included. Each term is - searched as **both ASCII and UTF-16LE bytes**. -3. **Deep PE analysis** on the first 5 hit binaries per term: - - which **registry APIs** the binary imports (`RegQueryValueExW`, - `RtlQueryRegistryValuesEx`, `ZwQueryValueKey`, …) — a binary that imports none - cannot be reading the value; - - the string's **virtual address and section**; - - **direct `.text` xrefs** — RIP-relative displacement matching back to the - string's RVA; - - if no direct xref, **`RTL_QUERY_REGISTRY_TABLE` tracing**: find the 8-byte - pointer to the string in `.rdata`/`.data`, read adjacent qwords for the - *destination global variable*, then look for code that reads that variable. - This distinguishes "the kernel populates a variable from this value **and code - uses it**" from "…and **nothing** reads it" (a legacy relic). -4. **Verdict**: - - | Verdict | Condition | - |---|---| - | 🔴 PLACEBO / FAKE TWEAK | 0 hits in any system binary | - | 🟢 ACTIVE DRIVER TWEAK | xrefs found in a `.sys` (or dxgi/dxgkrnl) | - | 🩵 SYSTEM MISMATCH | xrefs only in non-driver OS binaries | - | 🟡 DEAD STRING | string present, 0 code xrefs | - -5. **Sidecar output** — `verified_targets.json` contains only the GREEN entries; - the dashboard's *"Apply ONLY Verified Tweaks to Regedit"* button writes just those. - -**Why this is the right idea.** It replaces "a forum said this helps" with a -falsifiable, reproducible, machine-checkable claim. The **RED verdict is the -strongest signal**: if a value name appears nowhere in any Windows binary, no -amount of benchmarking noise can make it real. That is a cheap, decisive filter — -and one SockTuner can run offline, once, per candidate. - -## 2. Cross-check against SockTuner's own catalog - -[`SettingCatalog`](../src/SockTuner/Services/SettingCatalog.cs) holds 5 settings. -Four appear in Zenit's report: - -| SockTuner setting | Catalog path / evidence level | Zenit verdict | Reading | -|---|---|---|---| -| `TcpAckFrequency` | per-interface `…\Tcpip\Parameters\Interfaces`, *Experimental* | 🟢 **GREEN**, 3 hits | **Supports the entry.** Real value, and the evidence names the consumer | -| `TCPNoDelay` | per-interface, *Experimental* | 🔴 RED — **but see below** | **Verdict does not apply.** Zenit searched `TcpNoDelay`; the byte scan is case-sensitive and it never tested `TCPNoDelay` | -| `NetworkThrottlingIndex` | MMCSS system profile, *Documented* | 🟡 DEAD STRING | **Verdict unreliable.** Found in `mmcss.sys` but in section `INITCONS`; the scanner only walks `.text`, so init-time references are invisible to it | -| `SystemResponsiveness` | MMCSS system profile, *Documented* | 🩵 CYAN, 8 hits | **Supports the entry.** Real direct xref in `avrt.dll` (the MMCSS user-mode API); "no driver xref" is expected for a user-mode scheduler knob | -| `TcpDelAckTicks` | per-interface, *Experimental* | *not tested* | Open — a good first candidate to run the method against | - -### The concrete evidence worth recording - -- **`TcpAckFrequency`** → `C:\Windows\System32\drivers\tcpipreg.sys`, string at - `0x14000bb40` (`.rdata`, UTF-16LE), reached through a kernel registry table whose - destination variable `0x1400021d0` **is read by code** at `0x140001c23`. In - `tcpip.sys` the same value populates a variable that **nothing reads** ("legacy - relic"). So the live consumer is `tcpipreg.sys`, not `tcpip.sys`. -- **`Tcp1323Opts`** → same picture: a direct `.text` xref in `tcpipreg.sys`; in - `tcpip.sys` the string only lives in `.rsrc` (resources, not code). -- **`EnableRSS`** → hits **only in vendor NIC drivers** (`mlx4eth63.sys`, `mlx5.sys`, - `ipoib6x.sys`, Realtek `rtwlan*.sys`) — **not** in `tcpip.sys`. Zenit still marked - it GREEN and put it under `Tcpip\Parameters`. **This is the tool's central flaw - demonstrated live** (§3) — and it independently validates SockTuner's position: - RSS is a per-adapter NDIS keyword (`*RSS`), owned by the driver, not a global TCP knob. - -### The 15 values Zenit found nowhere in Windows - -`WaitToKillAppTimeout`, `TcpNoDelay`, `EnableTCPA`, `EnableDca`, `ArpCacheSize`, -`TcpCreateAndConnectTcbRateLimitDepth`, `NegativeSOACacheTime`, `GPU Priority`, -`MaxFreeTcbs`, `SFIO Priority`, `MaxSOACacheEntryTtlMax`, `SackOpts`, `EnableWsd`, -`GlobalMaxTcpWindowSize`, `NetFailureCacheTime`. - -Several are known XP/2003-era values genuinely removed from modern Windows -(`SackOpts`, `GlobalMaxTcpWindowSize`, `MaxFreeTcbs`), which is a decent sanity -check that the method's RED verdicts track reality. Treat the list as **"do not add -to the catalog without independent proof"**, not as settled fact — the MMCSS ones -(`GPU Priority`, `SFIO Priority`) are documented task-profile values and their RED -verdict is suspicious for the same `INITCONS`/section reason as above. - -## 3. Where the method breaks — read before trusting any verdict - -The idea is sound; this implementation is not rigorous enough to gate anything -automatically. Concretely: - -1. **It never checks the key path.** It matches value *names* only. A value can be - real, referenced by a driver, and still be read from a completely different key - than the `.reg` claims. Zenit's own `verified_targets.json` ships - `DisableTaskOffload` under `HKEY_CURRENT_USER\Control Panel\Desktop` — nonsense — - and marks it GREEN. `TcpAckFrequency` is likewise filed under the global - `Tcpip\Parameters` when the documented location is per-interface. -2. **Case-sensitive byte matching.** `TcpNoDelay` ≠ `TCPNoDelay`. A casing slip - produces a confident false RED (§2). -3. **The xref scanner is not a disassembler.** It walks `.text` byte by byte, accepts - any position whose first bytes look like a REX+LEA/MOV prefix, then unpacks a - displacement at a **fixed** `+3..+7` offset assuming a 7-byte instruction. It is - not instruction-aligned and not length-aware, so it both misses real references - and can fabricate spurious ones. -4. **It only scans `.text`.** Strings referenced from init-only/discardable sections - (`INITCONS` in `mmcss.sys`) are invisible → false "DEAD STRING". -5. **`candidates = hits[:5]`.** Only the first five hit binaries are analysed, in - arbitrary filesystem order. The actual consumer can be the sixth. -6. **`RTL_QUERY_REGISTRY_TABLE` tracing guesses the struct layout** by probing ±8 and - ±16 bytes around the string pointer. Loose heuristic, not the real layout. -7. **Presence ≠ effect.** Even a correct GREEN only proves *something reads the - value*. It says nothing about whether the value helps, what range is valid, or - whether the effect is measurable. - -**Net: RED with 0 hits is a strong negative signal. GREEN is a weak positive -signal.** Use it to *reject* candidates cheaply and to *locate the consuming -binary* for manual follow-up — never to auto-approve a write. - -## 4. What SockTuner should actually take from this - -**A research-side verification gate, not a shipped feature.** - -- **Do:** for each *global* (non-NDIS) registry knob in `SettingCatalog`, record in - the docs which Windows binary contains the value name and, where determinable, - what reads it. `TcpAckFrequency` → `tcpipreg.sys` is the template. This upgrades - an `EvidenceLevel` from an assertion to a citation. -- **Do:** use the cheap half of the method first — a case-insensitive ASCII+UTF-16LE - string search across `System32` (`findstr`/`rg -a` needs no `pefile`, no PE parsing, - no disassembly). That alone yields the decisive RED verdicts, which is most of the - value for a fraction of the complexity. -- **Do:** keep the "only apply what's verified" *principle*. SockTuner already - enforces it per-adapter (the driver is the allowlist); the gap is global values, - and this is a way to close it with documented evidence instead of a runtime scan. -- **Don't:** ship a System32 PE scanner in the product. It is slow, needs a PE - parser, its verdicts are not trustworthy enough to gate writes, and scanning every - system binary at runtime is exactly the kind of behaviour SockTuner shouldn't have. -- **Don't:** import `verified_targets.json` or the report's verdicts as fact. Two of - the five entries in that file have wrong key paths. - -**Suggested first pass** (offline, one-off, results into the docs): run the string -search for `TCPNoDelay` (correct casing), `TcpDelAckTicks`, `NetworkThrottlingIndex` -and `SystemResponsiveness`, and record which binaries and sections contain them. -That either substantiates or retires the two *Experimental* entries. - -## 5. PCIe capability-list walking (small, genuine improvement) - -`apply_pcie_tuning` now discovers the PCI Express Capability properly instead of -assuming a fixed offset: read the capabilities pointer at `0x34`, walk the linked -list (`cap_id` at `ptr`, next at `ptr+1`, masked `& 0xFC`) with a `visited` set to -break malformed loops, and stop at cap ID `0x10`. MRRS writes are followed by a -read-back that distinguishes "applied" from "hardware locked at its max". - -Out of scope for SockTuner (this is raw PCI config space via a kernel driver), but -it's the same two principles SockTuner already holds: **discover, don't hard-code**, -and **read back after writing**. Noted as convergence, nothing to import. - -## 6. NDIS block: trimmed, values flipped — and now orphaned - -`ZENOT_POWERSHELL_SCRIPT` is down to **44 properties** (from ~90). Notable changes -vs the values recorded in -[JACKPOTS_ZENIT_NDIS_CANDIDATES.md](JACKPOTS_ZENIT_NDIS_CANDIDATES.md): - -- **Offloads are now enabled, not disabled** — `*TCPUDPChecksumOffloadIPv4/6 = 3`, - `*LsoV2IPv4/6 = 1`, `*RscIPv4/6 = 1`, `*IPsecOffloadV2 = 3`. A straight reversal - of earlier versions' "disable everything" stance, with no stated rationale. Worth - noting as evidence that these value choices are fashion, not measurement. -- **Power/latency knobs still forced off** — `*EEE = 0`, `*FlowControl = 0`, - `*SelectiveSuspend = 0`, `*NicAutoPowerSaver = 0`, `*PacketCoalescing = 0`. -- `*ReceiveBuffers`/`*TransmitBuffers = 4096` — written blind, with no check against - the driver's advertised maximum. -- **`*JumboPacket = 1510`** — a nonsense value; standard settings are 1514 or - 9014/9614, and 1510 is below normal Ethernet framing. Good example of why - SockTuner validates against driver-advertised enums rather than copying constants. -- Writes go **directly to the class key** via `Set-ItemProperty`, bypassing - `Set-NetAdapterAdvancedProperty` and therefore all driver-side validation — still - the §0 anti-pattern from the 3.0 notes. - -**And it is now dead code.** `ZENOT_POWERSHELL_SCRIPT` is defined but referenced -nowhere: the function that executed it is gone from `IMOD-Test.py`, and `main()` -never dispatches `--network-stack` even though the flag is still parsed *and the -generated startup `.bat` still passes it*. The tool's headline networking feature -does nothing in 5.3. - -## 7. Four of five new flags are dead - -| Flag | Status | -|---|---| -| `--msr-cstate` | **Implemented** (`apply_cstate_lock` reaches `apply_msr_tweaks`) | -| `--pcie-mps` | Dead — `harmonize_mps` param exists, never passed by `main()`, never used in the body | -| `--pcie-ltr-clkreq` | Dead — same, `purge_ltr_clkreq` unused | -| `--usb-u0` | Dead — `force_u0` *is* passed into `process_usb_controller`, whose body never references it | -| `--nvme-apst` | Dead — parsed, referenced nowhere | -| `--network-stack` | Dead — parsed, not dispatched (§6) | - -The generated `IMOD_Profile.bat` passes all of them on every boot. Five of six -arguments are no-ops. - -## 8. Code duplication — the whole file-size increase - -`MainWindow` (lines 610–3602) has its **entire page-building body defined twice**: -`setup_hardware_page` at 1039 *and* 2321, `setup_gpu_page` at 1259 *and* 2541, and -the same for the power, maintenance and software-hub pages; -`apply_verified_tweaks_to_regedit` appears **three** times. Python silently keeps the -last definition, so roughly 1,300 lines are unreachable. This — not new features — -is what took the dashboard from 84 KB to 181 KB. - -Together with 5.0's truncated `IMOD-Test.py`, the dead flags (§7) and the orphaned -NDIS block (§6), it reinforces the standing caveat: **this corpus is hand-assembled -and frequently broken.** Every extracted value is a lead to verify, never a working -reference. - ---- - -## Net takeaways for SockTuner - -1. **Adopt the verification *method*, not the tool** (§1, §4). A one-off offline - string search over `System32` for each global registry knob in the catalog turns - `EvidenceLevel` into a citation. Start with the two *Experimental* per-interface - TCP entries. -2. **Record the concrete evidence already available** (§2): `TcpAckFrequency` and - `Tcp1323Opts` are consumed by `tcpipreg.sys`, not `tcpip.sys`. -3. **Don't act on Zenit's verdicts directly** (§3). The RED for `TcpNoDelay` is a - casing artefact and does not apply to SockTuner's `TCPNoDelay`; the DEAD STRING - for `NetworkThrottlingIndex` is a scanner limitation (`INITCONS` section), not - evidence against the setting. Neither catalog entry is invalidated by this report. -4. **`EnableRSS` independently validates "the driver is the allowlist"** (§2): the - name lives in vendor NIC drivers as an NDIS keyword, not in the TCP/IP stack as a - global value. -5. **Everything below the driver stays rejected** — RW.exe/WinRing0 MMIO and MSR - pokes, PCI config-space writes, the driver blocklist. Unchanged since 3.0. diff --git a/docs/JACKPOTS_ZENIT_7.0_LATENCY_SUITE_DELTA.md b/docs/JACKPOTS_ZENIT_7.0_LATENCY_SUITE_DELTA.md deleted file mode 100644 index 04b7262..0000000 --- a/docs/JACKPOTS_ZENIT_7.0_LATENCY_SUITE_DELTA.md +++ /dev/null @@ -1,197 +0,0 @@ -# Reference notes: Jackpot Latency Suite / Engine 7.0 — delta vs Zenit 5.3 - -> **Provenance and status.** Fifth note in the Zenit series, after -> [JACKPOTS_ZENIT_5.3_DELTA.md](JACKPOTS_ZENIT_5.3_DELTA.md). The new folder is -> `research/tools/Zenit/Zenit - Jackpot Latency Suite/`; its English manual identifies the -> product as "Jackpot's Hardware Register Engine v7.0". It was compared statically with -> `Zenit - 5.3/Zenit - 5.2/`. Nothing under `research/` was executed. -> The later local Engine v8.0 delta and final disposition are preserved in -> [`RESEARCH_ARCHIVE.md` §5](RESEARCH_ARCHIVE.md#5-delta-finale-zenit-latency-suite--engine-v80). -> -> **Nothing here is a verified recommendation and none of the code should be copied.** The -> useful result is a product lead to implement through SockTuner's existing native, typed, -> transactional path. - -## TL;DR - -| 7.0 change | Useful to SockTuner? | -|---|---| -| New `networktweaker/`: editable RSS profile, CPU range, processor count and receive queues | **Yes, one real gap.** SockTuner already reads this state from `MSFT_NetAdapterRssSettingData`; consider a native typed RSS setting after a read-only inventory increment and VM validation | -| Generic RSS presets for 4/6/8-core, HEDT and NUMA machines | **No.** They guess processor placement from core count and ignore processor groups, hybrid topology, actual indirection table, NIC locality and measured load | -| Data-driven registry tweak table, three-state “set/remove/unchanged” logic, JSONL audit and portable profiles | No new architecture. SockTuner already has catalogs, capability validation, exact snapshots, verification, audit and rollback; Zenit lacks the last four guarantees | -| `Nic.ps1` with PNP-to-driver resolution and per-write registry read-back | Principles already covered more safely. The same script also invents unsupported driver properties, disables bindings, resets Winsock/IP and cannot restore exact prior state | -| WinTweakVerifier v2 with Ghidra confidence tiers | **Research-only, still not evidence to import.** The shipped run has 0 dataflow-confirmed and 0 table-confirmed targets | -| AFD, global offload, interface and MSI controls | Already covered, intentionally deferred, or unsupported by evidence. No catalog addition justified | - -## 1. The one adoption candidate: native RSS topology control - -The new panel exposes six per-adapter RSS fields through `Set-NetAdapterRss`: - -- enabled state; -- profile (`Closest`, `ClosestStatic`, `NUMA`, `NUMAStatic`, `Conservative`); -- base and maximum processor; -- maximum processors; -- number of receive queues. - -SockTuner already reads those same fields in `WindowsOffloadInventory` from -`MSFT_NetAdapterRssSettingData`, but it does not expose that CIM instance as a writable typed -setting. NIC advanced properties such as `*RSS` and `*RSSProfile` are a related driver surface, -not a complete substitute for the operating-system RSS processor policy. - -This is a legitimate Windows surface. Microsoft documents `Profile`, processor group/number, -`MaxProcessors`, `NumaNode` and `NumberOfReceiveQueues` as read/write properties of -[`MSFT_NetAdapterRssSettingData`](https://learn.microsoft.com/en-us/windows/win32/fwp/wmi/netadaptercimprov/msft-netadapterrsssettingdata), -and documents the meaning and trade-offs of the profiles in -[`Set-NetAdapterRss` guidance](https://learn.microsoft.com/en-us/windows-server/networking/technologies/network-subsystem/net-sub-choose-nic). - -### Smallest safe SockTuner version - -1. **Read-only first:** add the actual `IndirectionTable`, `RssProcessorArray`, - `NumberOfInterruptMessages`, `MsiSupported`, `MsiXSupported` and `MsiXEnabled` fields already - exposed by the CIM class. This shows what CPUs the NIC really uses instead of inferring it from - the requested range. -2. **Then one typed composite setting:** snapshot and restore the complete RSS policy tuple for one - exact adapter. Start with the documented profile enum; add manual processor placement only when - the machine topology and processor groups can be validated. -3. Treat the operation as link-disruptive unless VM testing proves a narrower restart contract. - Re-read both the requested fields and the resulting indirection table after apply and rollback. -4. Do not ship Zenit's queue-count fallback. If the provider rejects a queue count, report the - unsupported value; never rewrite `Ndi\Params\*NumRssQueues\default` or manufacture enum entries. - -This belongs behind the existing Step 7b hardware-validation gate. It is not needed for the -current Step 10 release work and should not expand the immediate queue without real demand. - -## 2. Why the supplied RSS presets should not be copied - -The presets are fixed JSON guesses such as “RSS on CPUs 2-7 with four queues”. That is not a -hardware capability model: - -- the numbers are logical processors, not physical-core identities; -- processor groups are omitted, despite the backend and Windows API supporting them; -- hybrid P/E-core topology and SMT sibling placement are ignored; -- NIC NUMA locality and the live RSS processor array are ignored; -- no workload measurement selects between dynamic, static and conservative profiles; -- no driver-advertised queue maximum is checked. - -The panel also omits profile value 6, `Balanced`, which SockTuner's existing formatter already -recognises. Microsoft documents it as a NetAdapterCx option on heterogeneous-CPU systems. Static -“4-core/8-core” presets would therefore make SockTuner less correct than its current inventory. - -If RSS recommendations are added later, they should be derived from live topology plus measured -receive load, and remain editable proposals. A canned processor map is not a safe shortcut. - -## 3. The Network Tweaker architecture is below SockTuner's current baseline - -There are some sensible implementation ideas in isolation: - -- one data table drives the form and write logic; -- removing a registry value represents “driver default”; -- each log row records previous, requested and result states; -- adapter and command output are parsed as structured JSON rather than display text. - -SockTuner already has stronger versions of all four: setting catalogs/specifications, a fake-backed -transaction engine, capability-derived values, snapshot/read-back/exact rollback and an audit -store. The Zenit engine performs independent writes in sequence and reports “Apply Complete” even -after individual failures. It has no transaction boundary, stale-plan rejection, rollback or -post-write verification for the PowerShell/CIM paths. - -The “portable profile” loader validates only a `kind` string and the presence of a dictionary. A -profile can carry arbitrary setting IDs and free-text values, after which “Apply all” processes -every category. If SockTuner ever adds user profile import, the file must remain only an untrusted -proposal that is re-resolved through the live typed capability set. There is no current need to add -that attack surface. - -## 4. `Nic.ps1`: a better lookup wrapped around unsafe operations - -The useful detail is the adapter lookup: it follows a PNP instance's `Driver` value to the real -network class key instead of assuming that a WMI `DeviceID` is the four-digit class subkey. The -new `networktweaker` backend still makes that unsafe assumption (`DeviceID -> NNNN`), while -SockTuner avoids both approaches for advanced properties by addressing the CIM instance with the -adapter GUID. - -The script's central `Set-TypedRegistryValue` also reads each registry value back after writing. -That is good practice, but SockTuner already performs read-back inside a transaction and also owns -the snapshot and rollback that Zenit lacks. - -The rest should stay rejected: - -- it creates `Ndi\Params` definitions for `*UsoIPv4`, `*UsoIPv6`, `*UdpRsc`, `*RSS` and RSS queue - values even when the driver did not advertise them; -- it writes fixed Intel/Realtek maps, including previously rejected `HwOption*`, `ThreadPoll`, - `DisablePhyReset` and `PnPCapabilities` values; -- it forces RSS queue counts without checking hardware limits (16 in `Nic.ps1`, but the GUI's - “unlock” invents only 1-12); -- it disables every adapter binding except IPv4/IPv6, including security, capture, - virtualisation, discovery and sharing filters; -- it globally selects BBR2 from the OS build number instead of asking the live TCP provider what - the build supports; -- it runs broad IP, TCP and Winsock resets after applying settings, then calls those resets a - revert even though they cannot reproduce the captured pre-change state; -- its revert removes all present network devices with `pnputil` and rescans them; -- many `netsh`, cmdlet and direct `New-ItemProperty` writes bypass the checked helper, so the final - success counter does not cover the whole operation. - -There are also direct inconsistencies: the UI says it is enabling global RSC while the code passes -`Disabled`; the manual says the NIC operation uses `Disable-PnpDevice`/`Enable-PnpDevice`, while -the current paths use `Restart-NetAdapter`; and the manual claims `TCPNoDelay` is applied under a -global TCP key, while `Nic.ps1` does not set it in the apply path at all. - -These are useful negative tests for SockTuner's existing rules, not feature leads. - -## 5. WinTweakVerifier v2: improved labels, no new trustworthy result - -Version 7.0 adds Ghidra result tiers for: - -- a code reference in a function that calls a known registry API; -- claimed argument dataflow from the string to the call; -- a claimed `RTL_QUERY_REGISTRY_TABLE` structure match. - -The distinction is directionally right. The shipped 42-target report, however, contains -**0 dataflow-confirmed and 0 table-confirmed targets**. Forty targets sit in the weaker -“same function calls a registry API” tier and two strings are absent. The current report is about -graphics-driver power values, not SockTuner's TCP/NDIS candidates, so it supplies no new catalog -evidence. - -The new high-confidence implementations are also still heuristics: - -- “dataflow” records that the string address was loaded and that a later call within a 140- - instruction window targets a registry API; it does not track the destination register, argument - register, clobbers or control-flow path; -- “confirmed table” checks only that the four bytes eight bytes before a string pointer decode to - a small flags value; it does not validate the whole table entry, surrounding entries, terminator - or the call that consumes the table; -- as before, a value-name match does not prove the registry key path, expected type, accepted - range or performance effect. - -Therefore the 5.3 conclusion is unchanged: use offline binary work as a cheap negative filter and -as a way to locate candidate consumers, never as an automatic approval gate. No SockTuner evidence -level should change from the supplied 7.0 results. - -## 6. Remaining surfaces: no action - -- **AFD values:** the panel republishes old buffer/window “magic values” without current Windows - documentation, live capability metadata or benchmark evidence. Step 8 intentionally left these - out; nothing here closes that evidence gap. -- **IP interface fields:** most are routing, discovery or lifetime semantics rather than latency - controls. The generic UI assumes a returned property is safely writable and accepts numeric - free text without local ranges. SockTuner's selected MTU and metric controls are the useful, - reversible subset. -- **Global offloads:** already inventoried, and the provider-advertised writable subset already - goes through `CimGlobalPropertyCatalog`. Network Direct remains irrelevant to a normal gaming - desktop and has no new justification here. -- **MSI mode:** forcing `MSISupported=1` is not new and still lacks a capability-safe write model. - The read-only MSI/MSI-X fields on the RSS CIM class are useful inventory; interrupt placement is - already handled by SockTuner's typed affinity setting. -- **Custom profile sharing:** potentially pleasant UX, but not needed for the current release and - not worth adding untrusted-plan import until users ask for it. - -## Net recommendation - -Keep exactly one item from this release on the future list: - -> **Complete RSS inventory, then consider a typed native RSS profile/topology transaction using -> `MSFT_NetAdapterRssSettingData`.** - -Everything else is already present in a safer form, outside SockTuner's scope, or unsupported by -the evidence shipped with the suite. Do not copy the generic presets, registry tables, queue -“unlock”, WinTweakVerifier verdicts or `Nic.ps1` apply/revert workflow. diff --git a/docs/JACKPOTS_ZENIT_NDIS_CANDIDATES.md b/docs/JACKPOTS_ZENIT_NDIS_CANDIDATES.md deleted file mode 100644 index 69214eb..0000000 --- a/docs/JACKPOTS_ZENIT_NDIS_CANDIDATES.md +++ /dev/null @@ -1,183 +0,0 @@ -# Zenit NDIS property candidates + latency-tweak annotations (research input) - -> **Status: candidate list, not a catalog.** Untracked working note, companion to -> [JACKPOTS_ZENIT_4.0_DELTA.md](JACKPOTS_ZENIT_4.0_DELTA.md) / -> [JACKPOTS_ZENIT_REFERENCE.md](JACKPOTS_ZENIT_REFERENCE.md). -> -> SockTuner's NIC list is **hardware-verified**: `WindowsNdisInventory` and -> `WindowsAdapterCapabilityInventory` enumerate only what the driver actually advertises. -> [`NicKeywordCatalog`](../src/SockTuner/Services/NicKeywordCatalog.cs) then *annotates* that list — -> it never extends it. Each characterised keyword carries a tuning area, a `ChangeRisk`, and the -> trade-off in plain words; a keyword it has not characterised is reported as **high risk**, not as -> safe. `AdapterSettingCapability.Evidence` derives the level from the `*` prefix: standardized → -> driver-advertised, vendor → experimental. -> -> Characterisation can withhold a write but never authorise one. The seven §C keywords below are -> marked `Rejected`, which resolves to evidence level `Blocked` and makes -> `AdapterSettingCapability.Validate` refuse every value the driver offers for them — enforced -> inside the elevated worker, so a hand-built plan cannot bypass it. They stay visible in the -> read-only inventory with the reason attached. -> -> The ~90 properties below are the *superset the Zenit tool writes blindly by -> name*. They are kept here only as a -> **watch-list**: if a future compatibility report shows one on real hardware, promote it into the -> corpus with a real range/enum; until then it is a name to recognise, never a value to apply. -> **The Zenit "forced value" columns are the tool's opinion, unverified — do not import them.** - -## How to read the "Class" column - -The Microsoft NDIS convention is the cheap, reliable triage axis, and it maps 1:1 onto -SockTuner's existing risk model: - -- **`*` (standardized)** — a Microsoft-defined [standardized keyword]; the driver publishes an - `Ndi\params\` subkey with a `default`/`enum` the inventory can read. These are the - legitimate "driver-advertised" candidates. Safe to expose *when advertised*, at the range the - driver gives — never at a value we invented. -- **`vendor`** — no `*` prefix: a private, vendor-specific keyword. Sometimes advertised (has a - `ParamDesc`/`enum`), often just a raw registry value with no metadata and no public datasheet. - These are exactly the "permitted but uncharacterised → high risk" class SockTuner already - flags. Several here are Realtek/Intel internals with no documented meaning. - ---- - -## A. Standardized (`*`) keywords — legitimate candidates when the driver advertises them - -Cross-check each against `NicKeywordCatalog`; add the ones a compatibility report confirms. - -### Offloads (checksum / LSO / USO / RSC / IPsec / encap) -| Keyword | Zenit value | Note | -|---|---|---| -| `*IPChecksumOffloadIPv4` | 3 (Rx+Tx) | Standard checksum offload; 0=off,1=Tx,2=Rx,3=both. Enabling is normal, not a latency win per se. | -| `*TCPChecksumOffloadIPv4/IPv6` | 3 | " | -| `*UDPChecksumOffloadIPv4/IPv6` | 3 | " | -| `*TCPUDPChecksumOffloadIPv4/IPv6` | 3 | Combined variant on some drivers. | -| `*LsoV1IPv4`, `*LsoV2IPv4`, `*LsoV2IPv6` | 1 | Large Send Offload. Throughput feature; can *add* latency for small packets. | -| `*UsoIPv4`, `*UsoIPv6` | 1 | UDP Send Offload. | -| `*UdpRsc` | 1 | UDP Receive Segment Coalescing. Coalescing *raises* latency — note the contradiction with `*PacketCoalescing=0` below. | -| `*RscIPv4`, `*RscIPv6` | 1 | Receive Segment Coalescing. Same latency caveat; many low-latency guides *disable* RSC. Zenit enables it — treat as opinionated. | -| `*IPsecOffloadV1IPv4`, `*IPsecOffloadV2`, `*IPsecOffloadV2IPv4` | 3 | IPsec task offload. | -| `*EncapsulatedPacketTaskOffload`(+`Nvgre`,`Vxlan`) | 1 | NVGRE/VXLAN offload — datacenter feature, irrelevant to a gaming desktop. | -| `*QoSOffload` | 1 | 802.1p/DCB offload. | -| `*HeaderDataSplit` | 1 | RX header/data split. | - -### Interrupt moderation / RSS / polling -| Keyword | Zenit value | Note | -|---|---|---| -| `*InterruptModeration` | 1 | **The core latency knob.** Standardized enum (0/1). SockTuner should expose this as advertised. Note Zenit sets it *on* (=1) while also poking the hardware ITR to 0 via MMIO — inconsistent. | -| `*Rss` / `*RSS` | 1 | Receive Side Scaling on/off. Standardized. | -| `*RSSProfile` | 4 | RSS load-balancing profile (ClosestProcessor etc.). | -| `*RssBaseProcNumber` | 2 | First CPU for RSS queues. Machine-specific — a fixed 2 is a guess. | -| `*NumRssQueues` | 2 | RSS queue count. Driver-advertised range varies. | -| `*MaxRssProcessors` | 1 | Cap on RSS CPUs. | -| `*NdisPoll` | 1 | NDIS polling mode (Win11 NDIS 6.85+). See **Unsafe** re: pairing with `ThreadPoll`. | -| `*PacketDirect` | 1 | PacketDirect provider — niche, high-throughput path. | -| `*PacketCoalescing` | 0 | Disables RX coalescing (a real latency lever). Contradicts `*UdpRsc/*Rsc=1` above. | - -### Buffers / MTU -| Keyword | Zenit value | Note | -|---|---|---| -| `*ReceiveBuffers` | 4096 | RX descriptor ring. Driver-advertised max varies by NIC; 4096 may exceed advertised range → clamp. | -| `*TransmitBuffers` | 4096 | TX descriptor ring. Same clamp caveat. | -| `*JumboPacket` | 1510 | Jumbo frame size. 1510 ≈ "off/standard". | - -### Power management (all forced off) -| Keyword | Zenit value | Note | -|---|---|---| -| `*EEE` | 0 | Energy-Efficient Ethernet off. Legit low-latency lever, standardized. | -| `*SelectiveSuspend` | 0 | USB/idle suspend off. | -| `*NicAutoPowerSaver` | 0 | Auto power save off. | -| `*DeviceSleepOnDisconnect` | 0 | | -| `*EnableDynamicPowerGating` | 0 | | -| `*SSIdleTimeout`, `*SSIdleTimeoutScreenOff` | 1 | Selective-suspend idle timers. | -| `*WakeOnMagicPacket`, `*WakeOnPattern` | 0 | WoL off. Fine, unrelated to latency. | -| `*IdleRestriction` | 1 | | - -### Virtualization (off — irrelevant on a desktop) -| Keyword | Zenit value | Note | -|---|---|---| -| `*VMQ` | 0 | Virtual Machine Queues. | -| `*SRIOV` | 0 | SR-IOV. | -| `*NetworkDirect` | 0 | RDMA/NetworkDirect. | -| `*FlowControl` | 0 | See **Unsafe** — 802.3x pause frames. | - ---- - -## B. Vendor / undocumented keywords — recognise, do not import - -No `*` prefix. Expose only if advertised with metadata; otherwise these are the -"high-risk, uncharacterised" bucket. Grouped, Zenit values shown as the tool's guess. - -**Duplicate-of-standardized / driver internal moderation:** -`ITR=200`, `RxIntModeration=0`, `TxIntModeration=0`, `RssV2=1`, -`RecvCompletionMethod=4`, `SendCompletionMethod=2`, `AsyncReceiveIndicate=2`, -`ThreadedDpcEnable=0`, `TxThreadedDpcEnable=0`, `ThreadPoll=200000` *(see Unsafe)*. - -**Power / EEE / PHY (vendor variants of the `*` power knobs):** -`AdvancedEEE=0`, `EEEPlus=0`, `EEELinkAdvertisement=0`, `GigaLite=0`, -`EnableGreenEthernet=0`, `PowerSavingMode=0`, `AutoPowerSaveModeEnabled=0`, -`EnableSavePowerNow=0`, `EnablePowerManagement=0`, `EnablePME=0`, `PowerDownPll=0`, -`ReduceSpeedOnPowerDown=0`, `EnablePHYFlexibleSpeed=0`, `EnableD0PHYFlexibleSpeed=0`, -`EnableD3ColdInS0=0`, `DisableDelayedPowerUp=1`, `EnablePHYWakeUp=0`, -`EnableModernStandby=0`, `EnableDisconnectedStandby=0`, `EnableWakeOnManagmentOnTCO=0`, -`WakeOn=0`, `WakeOnLink=0`, `WakeOnFastStartup=0`, `WakeFromS5=0`, `S5WakeOnLan=0`, -`S0MgcPkt=0`, `ForceWakeFromMagicPacketOnModernStandby=0`, `WolShutdownLinkSpeed=2`. - -**ASPM / LTR / OBFF (PCIe link-power; also done via config space in §3/§4 of the 3.0 notes):** -`ASPM=0`, `EnableAspm=0`, `CLKREQ=0`, `DynamicLTR=0`, `ForceLtrValue=0`, -`LatencyToleranceReporting=0`, `LTROBFF=0`, `OBFFEnabled=0`. - -**Realtek/Intel private internals — no public datasheet meaning:** -`HwOption=12582912` (DWord), `HwOptionV2=4` (DWord), `HwOptionV3=262144` (DWord), -`PnPCapabilities=24` (DWord) *(see Unsafe)*, `I218DisablePLLShut=1`, -`I218DisablePLLShutGiga=1`, `I219DisableK1Off=1`, `DisableIntelRST=1`, -`ForceHostExitUlp=1`, `ULPMode=0`, `SipsEnabled=0`, `FecMode=0`, -`LinkNegotiationProcess=0`, `WaitAutoNegComplete=0`, `WaitForValidPhyIDRead=0`, -`DisablePhyReset=1` *(see Unsafe)*. - -**Misc behavioural:** -`DisableLLDP=1`, `StoreBadPackets=0`, `SleepWhileWaiting=0`, `EnableETW=0`, -`EnableCoalesce=0`, `DMACoalescing=0`, `CongestionMonitoringEnable=0`, -`VMQSupported=0`, `TeredoOffload=1`, `SSIdleTimeoutMS=1`, -`DropHighlyFragmentedPacket=1` *(see Unsafe)*. - ---- - -## C. Latency tweaks flagged **UNSAFE** (recognise the symptom, reject the method) - -These are the ones I'd *not* let into SockTuner as-is — either undocumented, high blast -radius, or actively harmful. Ordered roughly by severity. - -1. **Driver-blocklist disable** — `CI\Config\VulnerableDriverBlocklistEnable=0`. BYOVD enabler, - nothing to do with latency. Already the §0 hard-no. **Never.** -2. **Below-driver MMIO pokes** — Intel ITR `+0x00C4` / EEE `+0x0E00`, Realtek INT_MIT `+0x00EC` - / EEE `+0x00D4`, HD-Audio INTCTL `+0x08`. Undocumented offsets written behind the live - driver. The *documented* equivalent (`*InterruptModeration`, `*EEE`) already covers the goal. -3. **MSR pokes** — `IA32_ENERGY_PERF_BIAS` (0x1B0), AMD `0xC0010296` (undocumented DF C-state - lock). Out of networking scope + BSoD risk. The Zenit RW.exe path itself refuses MSR writes. -4. **`HwOption`/`HwOptionV2`/`HwOptionV3` (Realtek bitmasks)** — magic DWords with no public - meaning; wrong silicon revision = undefined behaviour. Guessed by the tool. -5. **`ThreadPoll=200000` + `*NdisPoll=1`** — busy/spin-poll the NIC. Can pin a CPU core at 100%, - raising power/heat/DPC on *other* devices; "lower latency" here trades a whole core. If ever - offered, must be explicit, measured, and default-off. -6. **`DisablePhyReset=1`** — suppresses PHY reset; can wedge link renegotiation after a - cable/speed change. Recovery may need a driver reinstall. -7. **`PnPCapabilities=24`** — sets the Device-Manager "allow the computer to turn off this - device" / WoL bits in one opaque DWord. Documented-ish but coarse; prefer the individual - `*`-power keywords so the change is legible and reversible per-setting. -8. **`*FlowControl=0`** — disabling 802.3x pause frames can cause RX drops on a congested or - slower link (a real regression, not just "no gain"). Situational, not a blanket win. -9. **`DropHighlyFragmentedPacket=1`** — silently drops legitimate fragmented traffic. Correctness - risk, not a latency setting. -10. **`*Rsc*/*UdpRsc=1` while chasing latency** — coalescing *adds* receive latency; enabling it - contradicts the stated goal. Not dangerous, but wrong-signed for a "low latency" preset — - flag as opinionated/incoherent rather than safe. -11. **Persistent MTU / `DisabledComponents=0x20` (IPv6 de-prioritise) / interface-metric=1** — - documented but *behavioural*, system-wide, and sticky (`store=persistent`, survives reboot). - Not unsafe per se, but must be snapshot + reversible, never a silent side effect. - -### Safe-ish latency levers worth keeping on the radar (documented, low blast radius) -`*InterruptModeration`, `*EEE`, `*FlowControl` *(situational)*, `*ReceiveBuffers`/`*TransmitBuffers` -*(clamp to advertised)*, `*Rss`+profile *(machine-specific tuning)*, MMCSS -`NetworkThrottlingIndex`/`SystemResponsiveness` *(already catalogued)*, and the TCP/IP knobs in -§7 of the 4.0 delta — all as **driver-advertised / documented, snapshot-and-rollback** entries, -which is what the existing catalog already does. diff --git a/docs/JACKPOTS_ZENIT_REFERENCE.md b/docs/JACKPOTS_ZENIT_REFERENCE.md deleted file mode 100644 index 5bcd05e..0000000 --- a/docs/JACKPOTS_ZENIT_REFERENCE.md +++ /dev/null @@ -1,229 +0,0 @@ -# Reference notes: "Jackpots Zenit 3.0" (Noverse IMOD tool) - -> **Provenance and status.** This document condenses technical values observed in a -> third-party tool (`C:\Users\Lorenzo\Downloads\Jackpots Zenit 3.0`, files `IMOD-Test.py`, -> `IMOD_Dashboard.py`, using the bundled `RW.exe` / `chiptool.exe` + WinRing0/InpOut -> kernel drivers). It is kept here purely as a **research input**, per the project's own -> engineering position in [README.md](../README.md#engineering-position): nothing below is -> a verified recommendation. Every value must be checked against official documentation -> (Intel/Realtek/AMD datasheets, Windows NDIS/TCP docs, PCIe spec) and validated on real -> hardware before it becomes a SockTuner feature or catalog entry. -> -> None of the code below should be copied. What's useful is the **list of knobs** and the -> **register/property names**, so nothing gets missed while building -> [`SettingCatalog`](../src/SockTuner/Services/SettingCatalog.cs) and the NDIS/TCP -> inventories. -> -> **Later versions:** [JACKPOTS_ZENIT_4.0_DELTA.md](JACKPOTS_ZENIT_4.0_DELTA.md) (4.0 delta, -> incl. the DPC/ISR measurement idea) · [JACKPOTS_ZENIT_5.0_DELTA.md](JACKPOTS_ZENIT_5.0_DELTA.md) -> (5.0 delta — no new networking knobs) · [JACKPOTS_ZENIT_5.3_DELTA.md](JACKPOTS_ZENIT_5.3_DELTA.md) -> (5.3 delta — the `WinTweakVerifier` placebo-detection method, the one genuinely -> useful item in the corpus). - -## 0. Do NOT replicate: security-relevant anti-pattern - -`IMOD-Test.py` calls this, unconditionally, on every run, with no UI disclosure: - -```python -def apply_driver_blocklist_tweak(): - key = winreg.OpenKey(HKEY_LOCAL_MACHINE, r"SYSTEM\CurrentControlSet\Control\CI\Config", ...) - winreg.SetValueEx(key, "VulnerableDriverBlocklistEnable", 0, REG_DWORD, 0) -``` - -This disables Microsoft's **Vulnerable Driver Blocklist** (part of HVCI/Smart App -Control). It's the standard first step of the BYOVD (Bring Your Own Vulnerable Driver) -pattern used by cheat loaders and malware to get an unsigned/vulnerable kernel driver -(here: WinRing0/InpOut) past Windows' own defenses. It has nothing to do with network or -PCIe latency. - -**Action for SockTuner:** never touch `HKLM\SYSTEM\CurrentControlSet\Control\CI\Config`. -If a future low-level driver path is ever considered, it must degrade gracefully when the -blocklist is enabled, never disable it. - -## 1. Coverage checklist vs. SockTuner's planned areas - -Cross-reference against [PRODUCT_SCOPE.md](PRODUCT_SCOPE.md) / -[ROADMAP.md](ROADMAP.md) "NIC tuning" and "Windows networking" areas — used to make sure -nothing in this tool's surface is missing from the catalog design (not to copy its values): - -| Area | Jackpots Zenit does it? | Mechanism | In SockTuner scope already? | -|---|---|---|---| -| NIC advanced NDIS properties (offloads, RSS, interrupt moderation, power) | Yes (~90 properties) | raw registry write under NIC's Class GUID key | Yes — `WindowsNdisInventory` / `SettingCatalog`, driver-advertised only | -| NIC hardware register poke (ITR/EEE) below the driver | Yes, Intel + Realtek specific | direct MMIO write via kernel driver | **Not planned** — see §3, high risk | -| PCIe MRRS / ASPM on GPU, NVMe, root bridge, NIC | Yes | direct PCI config space write via kernel driver | Not currently in scope; Windows exposes no supported API for this | -| USB xHCI interrupt moderation | Yes | direct MMIO write via kernel driver | Not currently in scope | -| CPU MSR (energy perf bias, AMD C-states) | Yes | `wrmsr` via kernel driver | Out of scope (CPU, not networking) | -| HD Audio interrupt throttling | Yes | direct MMIO write via kernel driver | Out of scope (audio, not networking) | -| TCP/IP registry globals (MinRto, TTL, TimeWait) | Yes | registry | Yes — `WindowsTcpSettingInventory` | -| MMCSS `NetworkThrottlingIndex` / `SystemResponsiveness` | Yes | registry | Matches Step 6 MMCSS work already gated in `SettingTransactionService` | -| `netsh` congestion provider / autotuning | Yes | shells out to `netsh` | README states "prefer documented APIs over scripts" — worth a native equivalent (`Set-NetTCPSetting` / IP Helper API) instead of shelling out | -| Disable Windows driver blocklist | Yes | registry | **Explicitly excluded**, see §0 | - -## 2. NIC advanced-property registry tweaks (the "Zenot" PowerShell block) - -Applied to `HKLM:\SYSTEM\CurrentControlSet\Control\Class\{4D36E972-...}\` -(the standard NDIS adapter class), gated only by a driver-description regex match for -`Intel|Realtek|Killer|Aquantia|Broadcom` — i.e. **not** checked against what the driver -actually advertises as supported, which is precisely the gap SockTuner's -"driver-advertised only" design principle (README, Product goals) already avoids. - -Grouped by theme (values as observed, for cross-checking against SockTuner's catalog — -not vetted): - -**Interrupt moderation / RSS** -`*InterruptModeration=1`, `ITR=200`, `*RSS=1`, `*RSSProfile=4`, `*RssBaseProcNumber=2`, -`*NumRssQueues=2`, `*MaxRssProcessors=1`, `RssV2=1`, `RxIntModeration=0`, -`TxIntModeration=0`, `RecvCompletionMethod=4`, `SendCompletionMethod=2`, -`ThreadedDpcEnable=0`, `TxThreadedDpcEnable=0`, `AsyncReceiveIndicate=2` - -**Offloads** -`*LsoV1IPv4=1`, `*LsoV2IPv4=1`, `*LsoV2IPv6=1`, `*UsoIPv4=1`, `*UsoIPv6=1`, -`*UdpRsc=1`, `*RscIPv4=1`, `*RscIPv6=1`, `ForceRscEnabled=1`, -`*TCPChecksumOffloadIPv4=3`, `*TCPChecksumOffloadIPv6=3`, `*UDPChecksumOffloadIPv4=3`, -`*UDPChecksumOffloadIPv6=3`, `*IPChecksumOffloadIPv4=3`, `*TCPUDPChecksumOffloadIPv4=3`, -`*TCPUDPChecksumOffloadIPv6=3`, `*TCPConnectionOffloadIPv4=1`, -`*TCPConnectionOffloadIPv6=1`, `*EncapsulatedPacketTaskOffload=1` (+Nvgre/Vxlan -variants), `*QoSOffload=1`, `TeredoOffload=1`, `HDSplitAlways=1`, `*HeaderDataSplit=1` - -**Power management / EEE (all disabled)** -`*EEE=0`, `AdvancedEEE=0`, `EEELinkAdvertisement=0`, `EEEPlus=0`, `GigaLite=0`, -`EnableGreenEthernet=0`, `PowerSavingMode=0`, `*NicAutoPowerSaver=0`, -`AutoPowerSaveModeEnabled=0`, `EnableSavePowerNow=0`, `*DeviceSleepOnDisconnect=0`, -`*EnableDynamicPowerGating=0`, `*SelectiveSuspend=0`, `EnablePowerManagement=0`, -`ReduceSpeedOnPowerDown=0`, `PowerDownPll=0`, `EnablePME=0`, `WakeOn=0`, -`WakeOnFastStartup=0`, `WakeOnLink=0`, `S0MgcPkt=0`, `S5WakeOnLan=0`, -`WakeFromS5=0`, `*WakeOnMagicPacket=0`, `*WakeOnPattern=0`, -`ForceWakeFromMagicPacketOnModernStandby=0` - -**ASPM / link power / latency tolerance** -`ASPM=0`, `EnableAspm=0`, `CLKREQ=0`, `LTROBFF=0`, `OBFFEnabled=0`, `DynamicLTR=0`, -`LatencyToleranceReporting=0`, `ForceLtrValue=0`, `EnableD0PHYFlexibleSpeed=0`, -`EnableD3ColdInS0=0`, `EnableModernStandby=0`, `EnableDisconnectedStandby=0` - -**Vendor/model-specific (Intel I218/I219 only — will no-op or error elsewhere)** -`I218DisablePLLShut=1`, `I218DisablePLLShutGiga=1`, `I219DisableK1Off=1` - -**Misc / buffers / driver internals** -`*ReceiveBuffers=4096`, `*TransmitBuffers=4096`, `*JumboPacket=1510`, -`*FlowControl=0`, `*VMQ=0`, `VMQSupported=0`, `*SRIOV=0`, `*NetworkDirect=0`, -`DropHighlyFragmentedPacket=1`, `CongestionMonitoringEnable=0`, `DMACoalescing=0`, -`EnableCoalesce=0`, `PacketCoalescing=0`, `*PacketDirect=1`, `*NdisPoll=1`, -`ThreadPoll=200000`, `EnableETW=0`, `DisableLLDP=1`, `SipsEnabled=0`, `FecMode=0`, -`StoreBadPackets=0`, `SleepWhileWaiting=0`, `ForceHostExitUlp=1`, `ULPMode=0`, -`WaitAutoNegComplete=0`, `WaitForValidPhyIDRead=0`, `LinkNegotiationProcess=0`, -`DisablePhyReset=0`, `DisableDelayedPowerUp=1`, `DisableIntelRST=1`, -`SSIdleTimeout=1`, `SSIdleTimeoutScreenOff=1`, `SSIdleTimeoutMS=1`, -`WolShutdownLinkSpeed=2`, `HwOption=12582912 (DWord)`, `HwOptionV2=4 (DWord)`, -`HwOptionV3=262144 (DWord)`, `PnPCapabilities=24 (DWord)` - -None of these are checked against what `WindowsNdisInventory`-style driver-advertised -enumeration would return — several (RSS profile/queue counts, `HwOption*`) are Realtek -RTL8125-specific internal bitmasks with no public datasheet meaning. Good candidates for -the hardware-capability probe effort already underway (README "Help wanted" section): -if a real report shows a property/range, add it to the catalog; if not, leave it out -rather than guessing the value like this tool does. - -## 3. Below-the-driver hardware register pokes (do not do this without a very good reason) - -`IMOD-Test.py` also writes directly into device MMIO space via the WinRing0/InpOut -kernel driver, bypassing the NIC driver entirely: - -| Vendor (PCI Vendor ID) | Register | Offset from MMIO BAR | Action | -|---|---|---|---| -| Intel (`0x8086`) | ITR (Interrupt Throttle Register, global) | `+0x00C4` | write `0x00000000` | -| Intel (`0x8086`) | EEE Control | `+0x0E00` | write `0x00000000` | -| Realtek (`0x10EC`) | INT_MIT (interrupt mitigation) | `+0x00EC` | write `0x00000000` | -| Realtek (`0x10EC`) | EEE Power Lock | `+0x00D4` | write `0x00000000` | -| HD Audio controller (any) | INTCTL (interrupt control) | `+0x08` | OR in bit 31 | - -These offsets are undocumented/reverse-engineered (no datasheet citation in the source), -apply to whatever silicon revision the vendor ID matches without further validation, and -write behind the back of the driver that's supposed to own that memory — a live driver -can race the write, revert it, or crash. This is fundamentally incompatible with -SockTuner's stated goal ("prefer documented Windows APIs and driver capabilities over -scripts") and its "no third-party command-line tools for normal operation" principle. -Flagging only so the *symptom* it's chasing (interrupt moderation / EEE) is recognized as -already covered, more safely, by the NDIS properties in §2 -(`*InterruptModeration`, `*EEE`, `ITR`) — the MMIO route adds risk without adding a -capability SockTuner doesn't already plan to expose. - -## 4. PCIe MRRS / ASPM (generic, spec-documented — unlike §3) - -Unlike the vendor pokes above, this part walks the **standard PCI Express Capability -structure** (PCIe spec, not reverse-engineered): - -- Confirm PCI Status register (offset `0x06`) bit 4 (Capabilities List) is set. -- Walk the capability linked list from offset `0x34` looking for Capability ID `0x10` - (PCI Express Capability). -- **Device Control Register** = `cap_offset + 0x08`; bits 12-14 = Max Read Request Size - (MRRS): `0`=128B … `5`=4096B. -- **Link Control Register** = `cap_offset + 0x10`; bits 0-1 = ASPM control (`00`=disabled). - -Windows doesn't expose a supported API for PCIe config-space MRRS/ASPM control, so there's -no safe path to this without a kernel driver of some kind — noting it here as a boundary -of what's reachable "properly" from user mode, not as something to implement the same way. - -## 5. USB xHCI interrupt moderation (generic, spec-documented) - -Also standard (xHCI spec, not vendor-specific): `RTSOFF` (Runtime Register Space Offset) -lives at MMIO BAR `+0x18`; each interrupter's IMOD register is at -`RuntimeBase + 0x20 + (interrupter_index * 0x20) + 0x04`, and setting it to `0` disables -interrupt coalescing for that interrupter. Same caveat as §4 — no supported Windows API -surface for this; noted for completeness only. - -## 6. CPU MSRs (out of SockTuner's networking scope, noted for completeness) - -- `IA32_ENERGY_PERF_BIAS` (MSR `0x1B0`) — documented in the Intel SDM, forced to `0` - (max performance). Also present on AMD. -- AMD-specific MSR `0xC0010296` ("Data Fabric C-State Lock") — undocumented in public AMD - docs, reverse-engineered. Same risk profile as §3. - -CPU power/C-state tuning is outside SockTuner's networking-stack scope per -[PRODUCT_SCOPE.md](PRODUCT_SCOPE.md); listed only in case a future "system" adjacent tool -in the same family wants it. - -## 7. Windows/TCP registry values used (legitimate, documented territory) - -``` -HKLM\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters - MinRto=300 (DWord), DefaultTTL=64 (DWord), TcpTimedWaitDelay=30 (DWord) - -HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Multimedia\SystemProfile - NetworkThrottlingIndex=10 (DWord), SystemResponsiveness=10 (DWord) -``` - -Plus, shelled out via `netsh` rather than a native API call: - -``` -netsh int tcp set supplemental Template=Internet CongestionProvider=CTCP -netsh int tcp set global autotuninglevel=normal -``` - -These are all documented, low-risk, standard Windows tuning knobs — the -`NetworkThrottlingIndex`/`SystemResponsiveness` pair overlaps with the MMCSS work already -gated through `SettingTransactionService` (README "Step 6"). The `netsh` TCP settings are -reachable natively via `Set-NetTCPSetting`/IP Helper API equivalents, consistent with the -project's "no third-party command-line tools" goal — `netsh` itself already isn't -third-party, but a native P/Invoke path avoids a process-shell-out for something with a -documented API. - -## 8. Design anti-patterns observed (already avoided by SockTuner's plan — kept as a checklist) - -These map directly to principles already stated in [README.md](../README.md), listed here -just as concrete "this is the failure mode we're avoiding" examples: - -- **Fixed device addressing.** BDF (bus:device.function) values are captured once at - "Save Startup" time and hard-coded into a generated batch file; a BIOS update, slot - change, or bus renumbering silently targets the wrong device or a device that no longer - exists. → SockTuner should always resolve the target adapter/device dynamically at - apply time, not cache a topological address. -- **No rollback / no dry-run / no diff preview.** Values are written directly with no - snapshot of the prior state. → matches the already-planned Step 5 dry-run cart + - rollback + audit history. -- **Driver-description regex instead of capability query.** NIC family is matched by - string (`Intel|Realtek|Killer|...`) instead of asking the driver what it actually - supports. → matches the already-stated "expose only settings the NIC driver actually - advertises" principle. -- **Silent, undocumented, high-blast-radius side effect.** The driver-blocklist disable - (§0) is the clearest example: an action far outside the stated purpose of the tool, - applied with no user-facing disclosure. diff --git a/docs/PRODUCT_SCOPE.md b/docs/PRODUCT_SCOPE.md deleted file mode 100644 index d3c3d7c..0000000 --- a/docs/PRODUCT_SCOPE.md +++ /dev/null @@ -1,168 +0,0 @@ -# Product Scope - -## 1. Product definition - -SockTuner is an expert Windows network workbench: inventory, diagnostics, controlled tuning, verification, and recovery in one desktop application. - -Its value is not the number of registry keys it can write. Its value is making supported settings discoverable, comparable, measurable, and reversible across Windows builds and NIC drivers. - -## 2. Primary users - -- PC and network technicians; -- system integrators and performance tuners; -- competitive gamers who understand networking trade-offs; -- administrators investigating Windows endpoint networking; -- power users replacing collections of one-off scripts. - -SockTuner will not hide technical terminology or pretend that one profile is optimal for every machine. - -## 3. Proposed feature set - -### 3.1 Inventory and baseline — v1 - -- Windows edition, build, architecture, and reboot state. -- CPU topology relevant to RSS and interrupt placement. -- Physical and virtual adapter classification. -- Stable adapter GUID, PNP identity, PCI vendor/device ID, driver provider/version/date, NDIS version, link speed, and status. -- IPv4/IPv6 addresses, gateways, routes, metrics, MTU, DNS servers, and active network profile. -- Adapter bindings, power-management state, global offloads, TCP templates, QoS policies, and Winsock providers. -- Driver-advertised advanced properties with raw keyword, display label, current value, valid values/range, and default when available. -- Exportable JSON diagnostic snapshot and redacted support report. - -### 3.2 Change safety — v1 - -- Change cart with current and proposed values. -- Dry-run diff before UAC. -- Per-setting compatibility, evidence, trade-off, risk, and restart labels. -- Exact pre-change snapshot. -- Deterministic apply and independent read-back verification. -- Per-session history and rollback. -- Adapter-restart and reboot coordination. -- Partial-failure recovery and actionable errors. - -### 3.3 NIC and driver tuning — v1, capability-dependent - -- RSS state, profile, queue count, and supported CPU parameters. -- RSC, LSO, checksum offload, USO/URO, and other advertised offloads. -- Interrupt moderation and driver-advertised moderation rate. -- Receive/transmit buffers and queues within advertised ranges. -- Flow control, jumbo frames, VLAN/priority tagging, and link settings. -- EEE, Green Ethernet, selective suspend, wake options, and adapter power management. -- Bindings inventory; risky binding changes remain separate and never use “disable everything except IPv4/IPv6.” -- Vendor-neutral discovery, with tested guidance for common Intel and Realtek Ethernet adapters first. - -Rules: - -- A missing property is “unsupported,” not an invitation to inject a registry key. -- Values are discovered from the installed driver rather than guessed from the adapter brand. -- Throughput, CPU load, virtualization, Wake-on-LAN, and energy use trade-offs are always shown. - -### 3.4 TCP/IP, interface, and Winsock — v1 - -- TCP auto-tuning, ECN, timestamps, RSC, initial RTO, and available congestion-control templates. -- IPv4/IPv6 MTU, interface metrics, DNS configuration, and selected advanced interface properties. -- Path-MTU discovery and a guided MTU change; no hard-coded ISP table as an authoritative answer. -- TCP ACK/Nagle controls scoped to selected interfaces, clearly marked as TCP-only and experimental where documentation is insufficient. -- QoS policy inventory and supported egress policy editing. -- Winsock protocol and namespace catalog inspection. -- Targeted repair actions only when exact recovery is available; broad stack resets are not normal tuning operations. - -The first release excludes undocumented AFD/NDIS “magic values,” forced congestion providers that the OS does not expose as supported, blanket IPv6 removal, and global changes to every hidden adapter. - -### 3.5 Gaming diagnostics — v1 - -The diagnostic workflow must answer more than “is ping high?” It should isolate the first boundary at which latency, jitter, or loss appears. - -- Configurable, concurrent probes to the local gateway, first reachable ISP boundary, neutral reference targets, and a selected game endpoint. -- Sent/received/lost counts plus minimum, average, maximum, median, P95, and P99 RTT. -- A documented jitter calculation, raw sample timeline, and spike distribution. -- Repeated route sampling to detect path changes and persistent latency steps without misreading ICMP rate limiting as packet loss. -- DNS resolution timing, failures, returned-address comparison, and a clear distinction between connection setup and in-session latency. -- TCP connection timing and UDP/game-endpoint reachability where the protocol permits a valid test. -- IPv4 path-MTU discovery using the Don’t Fragment behavior, multiple targets, and explicit ICMP-blocked results. -- NIC/link counters and configuration correlation to detect local errors, power-saving transitions, driver problems, or incompatible tuning. -- Guided classification of likely causes: PC/NIC, Ethernet/Wi-Fi LAN, router/modem, access-link saturation, ISP edge, routing/peering, server distance/region, or remote service. -- Confidence-ranked findings with supporting and contradicting evidence; “inconclusive” is a valid result. -- Targeted local fixes only when SockTuner controls the cause; otherwise router guidance or an exportable ISP/support report. -- Baseline and post-change runs with identical targets, intervals, sample counts, and load conditions. -- JSON and self-contained HTML export. - -Loaded-latency testing should measure gateway, ISP, reference, and game-path behavior before, during, and after controlled download/upload load. It requires an explicitly selected test endpoint and must explain when router-side SQM/AQM, ISP intervention, a different game region, or server-side action is the real remedy. - -Initial game targets may come from a known profile or direct user input. Automatic process-to-remote-endpoint correlation is a later native ETW feature. - -### 3.6 Profiles and recommendations — after the change engine - -Initial profiles should be few and transparent: - -- **Windows Default / Restore Snapshot** — restores captured values, not guessed defaults. -- **Balanced** — preserves throughput and power behavior unless a documented issue is detected. -- **Low Latency** — proposes supported latency/CPU trade-offs for the selected adapter. -- **Custom** — user-selected values with validation. - -A profile is an editable change plan. It must never silently change unrelated devices or settings. - -Recommendations use system facts and measured results. They do not claim that disabling ECN, RSS, auto-tuning, checksum offload, or interrupt moderation is universally correct. - -### 3.7 Reporting and comparison — after native diagnostics - -- Before/after timelines and metric deltas. -- Multiple-run history with consistent test parameters. -- Machine-readable JSON schema with a version number. -- Self-contained HTML reports without CDN dependencies. -- Optional report redaction before sharing. -- Clear separation of observation, interpretation, and recommendation. - -## 4. Later features - -These remain outside v1 until the core is stable: - -- import of Waveform, LibreQoS, or other bufferbloat reports; -- browser-assisted test launch and result correlation; -- import and correlation for additional loaded-latency and throughput test services; -- automatic process-to-remote-endpoint correlation and game session analysis; -- ETW-based packet/flow timing analysis; -- optional PCAP import; -- Wi-Fi-specific radio and roaming controls; -- Marvell/Aquantia, Mellanox/NVIDIA, Killer, USB, and enterprise NIC validation packs; -- CLI automation and signed profile import/export; -- ARM64 builds and managed deployment. - -## 5. Explicitly deferred or rejected - -| Item | Decision | -| --- | --- | -| One-click “optimize everything” | Rejected: hides scope and produces unsafe global changes | -| Custom packet-capture kernel driver | Deferred: signing, security, stability, and maintenance cost are not justified for v1 | -| Required Wireshark, Npcap, tshark, curl, or PowerShell | Rejected for normal operation | -| Automatic driver download/update | Deferred: separate supply-chain and recovery problem | -| Router configuration | Out of scope for the Windows desktop core | -| Cloud accounts and telemetry | Not planned for v1 | -| Community tweak marketplace/plugins | Deferred until a secure, evidence-based format is proven necessary | -| Creating unknown driver registry keys | Rejected | -| Device removal as “rollback” | Rejected | -| Broad IP/Winsock reset as profile rollback | Rejected | - -## 6. Accuracy boundaries - -SockTuner can tune and measure the Windows endpoint. It cannot: - -- reduce propagation delay or move a game server closer; -- guarantee lower ping, jitter, packet loss, or bufferbloat; -- control congestion inside an ISP or remote network; -- replace router-side SQM/AQM for every bufferbloat problem; -- infer gaming performance from DNS response time; -- make a TCP tweak improve a UDP workload by definition; -- guarantee that a driver update preserves vendor-specific setting semantics. - -These boundaries should remain visible in product documentation and recommendations. - -## 7. Source-material policy - -The local scripts, reports, binaries, nested repositories, and third-party tools are a private research corpus. Before public release: - -- verify every technical claim independently; -- identify copyright and redistribution terms; -- do not copy third-party code without compatible permission; -- remove external executables, captures, personal reports, and nested `.git` directories from the distributable repository; -- keep only original documentation, validated implementation, test fixtures with clear provenance, and required notices. diff --git a/docs/README.md b/docs/README.md index f34eed3..aca8c0a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,8 @@ # SockTuner Documentation -This directory contains only project-owned planning and product documentation. - | File | Purpose | | --- | --- | -| [Architecture](ARCHITECTURE.md) | Technology choices, runtime shape, Windows integration, privilege boundary, setting model, diagnostics, security, and testing | -| [Product Scope](PRODUCT_SCOPE.md) | Intended users, v1 features, gaming diagnostics, later features, exclusions, and accuracy boundaries | -| [Implementation Roadmap](ROADMAP.md) | Ordered delivery phases and exit criteria from specification to public 1.0 | -| [GitHub Metadata](GITHUB.md) | Repository description, topics, About settings, and public-launch checklist | -| [Development](DEVELOPMENT.md) | Safe local commands, mutation isolation, CI, signing, and the automated pre-release process | - -The repository root [README](../README.md) is the concise project overview. - -## Research material +| [Architecture](ARCHITECTURE.md) | Runtime shape, Windows integration, safety, diagnostics, and testing | +| [GitHub metadata](GITHUB.md) | Repository description, topics, settings, and release checklist | -[RESEARCH_ARCHIVE.md](RESEARCH_ARCHIVE.md) conserva inventario, provenienza e conclusioni del corpus analizzato. Il materiale voluminoso e i programmi di terzi sono stati rimossi da `research/`; restano soltanto note, link e risultati leggeri come provenienza. Nessun elemento del corpus è automaticamente codice di produzione o una raccomandazione validata. +The repository root [README](../README.md) contains the project overview and usage information. diff --git a/docs/RESEARCH_ARCHIVE.md b/docs/RESEARCH_ARCHIVE.md deleted file mode 100644 index 24893b0..0000000 --- a/docs/RESEARCH_ARCHIVE.md +++ /dev/null @@ -1,217 +0,0 @@ -# Archivio delle conclusioni del corpus `research/` - -> Documento sostitutivo per il materiale di ricerca voluminoso rimosso dal PC. Conserva provenienza, inventario e decisioni utili a SockTuner; non rende autorevole né riutilizzabile il materiale originale. -> -> Analisi: **solo statica**, conclusa il **10 settembre 2026**. Nessuno script o binario del corpus è stato eseguito. - -## 1. Regole di interpretazione - -- Script, preset, database e report di terzi erano fonti di idee, non specifiche tecniche. -- Un valore leggibile o scrivibile non è automaticamente supportato, efficace o vantaggioso. -- Una stringa trovata in un binario prova meno di un consumer confermato; un consumer confermato prova meno di un effetto misurato. -- L’assenza da una scansione statica o da una breve traccia runtime non prova che un valore sia placebo. -- Ogni mutazione SockTuner resta subordinata a capacità live, snapshot tipizzato, validazione, read-back, verifica dell’effetto e rollback esatto. -- Nessun codice privo di licenza esplicita viene copiato o redistribuito. - -## 2. Inventario congelato prima della pulizia - -Dimensioni e conteggi si riferiscono a `C:\Users\Lorenzo\Documents\Projects\SockTuner\research` prima della rimozione dei programmi. - -| Area | File | Byte | Contenuto | Disposizione | -| --- | ---: | ---: | --- | --- | -| `links/` | 3 | 2.673 | URL, shortcut e riferimento Win Toolkit | conservato | -| `notes/` | 4 | 14.001 | teoria, comandi NDIS, idea route optimizer, nota remota non sicura | conservato | -| `projects/` | 170 | 159.914.579 | GameNetAnalyzer e studi/script bufferbloat | spostato nel Cestino il 10 settembre 2026 | -| `results/` | 4 | 808.258 | CSV, JSON e screenshot di test personali | conservato | -| `scripts/` | 22 | 1.473.895 | diagnostica e tuning PowerShell/batch | spostato nel Cestino il 10 settembre 2026 | -| `tools/` | 6.126 | 3.140.221.321 | utility, binari, screenshot e cinque generazioni Zenit | spostato nel Cestino il 10 settembre 2026 | -| **Totale** | **6.330** | **3.302.436.244** | escluso `research/README.md` | — | - -Spazio spostato nel Cestino: **3.301.609.795 byte** (circa **3,07 GiB**) da `projects/`, `scripts/` e `tools/`. - -### 2.1 Script - -`diagnostics/` conteneva: - -- `FIND-NIC-CLASS-PATH.bat`; -- `Get Adapter_GUID&PATH.ps1`; -- `NetworkDiagnostics.ps1`; -- `gaming_net_diagnostic.ps1`; -- `sniff_game_server.ps1`. - -`tuning/` conteneva: - -- `Auto MTU.bat`; -- `Command Lines BBR_FIX_W11.bat`; -- `DEVICE-TWEAKER-UPDATE-2026-LLG-X-LLC-UPDATED.ps1`; -- `DISABLE-POWERSAVING.bat`; -- due copie di `Disable Nagle Algorithm.ps1` e `Disable Nagle’s Algorithm.bat`; -- `Disable-NIC-PowerSavings.ps1`; -- `InterruptModerationLevel.ps1`; -- `Low_Latency.bat`; -- `Network Adapter Settings.bat`; -- `Network Test.bat`; -- `Network Tweaker 20230709.ps1`; -- `NetworkOptimizer.ps1`; -- `OPTIMIZE-NETWORKING.bat`; -- `Zenit_by_Jackpot_23.04.2026.ps1`; -- `disablenetworkpowermanagement.ps1`. - -Conclusione conservata: i comandi di inventario sono utili come checklist, ma le raccomandazioni “sempre disabilita” e i valori fissi non sono evidenza. SockTuner usa API/CIM native e proprietà dichiarate dal driver, non esegue questi script. - -### 2.2 Progetti - -| Progetto | Provenienza congelata | Licenza osservata | Conclusione conservata | -| --- | --- | --- | --- | -| `GameNetAnalyzer` | `https://github.com/PrimeBuild-pc/GameNetAnalyzer`, commit `4a7919fef9d645c964f49c2ae36b3e9618dbe339` | MIT | metriche di sessione, jitter/burst/spike, confronto run ed endpoint di gioco sono utili; SockTuner evita la dipendenza tshark/Npcap e preferisce socket/ETW nativi | -| `Bufferbloat vs` | `https://github.com/PrimeBuild-pc/bufferbloat-analysis`, commit `1136e3aa7d9837fa03824d2e582fbcd0ceef2052` | nessun file di licenza osservato nella copia | confrontare latenza idle e sotto carico; percentili e direzioni separate; la correzione reale è di norma SQM/AQM sul router | -| `bufferbloat-bufferbloat` | origine non documentata, sette batch locali | non identificata | nessun codice da riusare; i batch applicano ricette, non una diagnosi affidabile | - -La cattura GameNetAnalyzer includeva un PCAP personale di circa 110 MB e report derivati: erano esempi, non fixture pubblicabili. - -### 2.3 Tool - -| Cartella | File | Byte | Decisione | -| --- | ---: | ---: | --- | -| `FAST-screens` | 35 | 3.133.756 | conservati concettualmente baseline, confronto e guida; rifiutati percentile cloud, geolocalizzazione necessaria e geofence/firewall dei datacenter | -| `Registry_Truth_S.U.C.Ker` | 14 | 214.085.684 | utile l’idea di diff `.reg`/stato live e traccia runtime; database e verdict non sono attendibili né licenziati per l’import | -| `Script & tools` | 7 | 26.077.533 | GoInterruptPolicy resta un riferimento separato; gli altri script/preset non diventano catalogo | -| `Star Ethernet Analyzer` | 7 | 103.716.596 | utile importare serie CSV di RTT, jitter e loss; non copiare grade basato soltanto su `max RTT - min RTT` o medie aggregate | -| `WinMTR-v092` | 19 | 4.250.224 | WinMTR GPLv2 dimostra l’utilità di ping/traceroute ripetuti; SockTuner implementa la funzione nativamente e non include il binario | -| `Zenit` | 6.044 | 2.788.957.528 | cinque generazioni analizzate staticamente; conclusioni nei documenti Zenit e nel §5 | - -`Registry_Truth_S.U.C.Ker` associava eventi Procmon ai soli nomi valore tramite substring e poteva chiamare “default usato” una semplice assenza. Il suo backup ometteva i valori originariamente assenti e quindi non consentiva rollback esatto. L’idea di osservazione runtime resta valida soltanto con matching del percorso completo e senza trasformare “non osservato” in un verdetto negativo. - -### 2.4 Link, note e risultati rimasti - -- `links/repo.txt`: repository PrimeBuild per GameNetAnalyzer e Network-Tweaker. -- `pingpackettest.com-game-pro-esports.url` e `Win Toolkit.lnk`: riferimenti esterni, non dipendenze. -- `notes/route-optimization-feature-idea.md`: un prodotto ExitLag/LagoFast richiede relay e transit propri; SockTuner può al massimo misurare percorsi già disponibili o un relay portato dall’utente, previa revisione separata. -- `notes/Fortnite Ping Tool.txt`: contiene `irm ... | iex`; pattern esplicitamente rifiutato. -- `notes/Teoria rete.txt`: contiene affermazioni universali e valori fissi non dimostrati; mantenuta solo come provenienza delle idee. -- `results/`: quattro risultati personali utili come esempi manuali, non come benchmark generalizzabili. - -## 3. Conclusioni funzionali consolidate per SockTuner - -### Da mantenere - -1. Inventario per adapter con identità stabile, driver, link, proprietà avanzate e capacità live. -2. Misure separate di latenza base, jitter, perdita, stabilità nel tempo e latenza sotto carico. -3. Traceroute ripetuto e distinzione fra host, LAN/router, access link e routing/peering. -4. Confronti prima/dopo e fra sessioni, con contesto del carico e del tick rate. -5. Correlazione processo-endpoint tramite ETW o altra fonte nativa affidabile, non euristiche sul nome del processo o su endpoint UDP inesistenti. -6. Diagnosi bufferbloat con spiegazione che endpoint tuning non sostituisce SQM/CAKE/FQ-CoDel sul router. -7. Catalogo driver-advertised: valori enum/range del driver sono l’allowlist; proprietà vendor non documentate restano inventario o ricerca. -8. Piani trasparenti e atomici, mai pulsanti opachi “ottimizza tutto”. - -### Da rifiutare - -- disabilitare universalmente ECN, auto-tuning, timestamp, offload, flow control, RSS o interrupt moderation; -- derivare RSS soltanto dal numero di core o forzare queue count fuori capacità; -- scrivere valori NDIS non pubblicizzati o creare `Ndi\Params` per simulare supporto; -- applicare Nagle/ACK registry tweaks a tutte le interfacce come ottimizzazione gaming UDP; -- assumere MTU da ISP o da un probe fallito; -- disabilitare tutti i binding tranne IPv4/IPv6; -- usare reset Winsock/IP come rollback; -- installare driver, runtime o pacchetti tramite URL mutabili o pipeline `download-and-execute`; -- trasformare un read-back, una stringa binaria o una singola traccia in prova di beneficio; -- includere PCAP, report personali, database sconosciuti o binari del corpus nel prodotto. - -## 4. Mappatura al progetto - -Le decisioni già assorbite sono descritte principalmente in: - -- [`ARCHITECTURE.md`](ARCHITECTURE.md): API native, confine privilegi, diagnostica e limiti di accuratezza; -- [`DELIVERY_PLAN.md`](DELIVERY_PLAN.md): integrazione del corpus, catalogo NDIS/TCP, misure e remediation; -- [`ROADMAP.md`](ROADMAP.md): stato dei workstream, evidence note, bufferbloat e funzioni rinviate; -- [`PRODUCT_SCOPE.md`](PRODUCT_SCOPE.md): esclusioni e promesse che il prodotto non può fare; -- serie [`JACKPOTS_ZENIT_REFERENCE.md`](JACKPOTS_ZENIT_REFERENCE.md), [`JACKPOTS_ZENIT_4.0_DELTA.md`](JACKPOTS_ZENIT_4.0_DELTA.md), [`JACKPOTS_ZENIT_5.0_DELTA.md`](JACKPOTS_ZENIT_5.0_DELTA.md), [`JACKPOTS_ZENIT_5.3_DELTA.md`](JACKPOTS_ZENIT_5.3_DELTA.md), [`JACKPOTS_ZENIT_7.0_LATENCY_SUITE_DELTA.md`](JACKPOTS_ZENIT_7.0_LATENCY_SUITE_DELTA.md) e [`JACKPOTS_ZENIT_NDIS_CANDIDATES.md`](JACKPOTS_ZENIT_NDIS_CANDIDATES.md). - -L’unico gap concreto già emerso da Zenit 7.0 resta il controllo RSS nativo e tipizzato: prima completare l’inventario, poi eventualmente trattare l’intera tupla RSS come una transazione con verifica dell’indirection table. Nessun preset generico e nessun fallback registry. - -## 5. Delta finale: Zenit Latency Suite / Engine v8.0 - -### 5.1 Provenienza e confronto - -Percorso originale del corpus condiviso con ZapTweaks, successivamente spostato nel Cestino: - -`C:\Users\Lorenzo\Downloads\Zenit Latency Suite` - -La GUI dichiara Engine v8.0; launcher e manuali riportano ancora v7.0. Il corpus nuovo contiene **6.091 file / 3.840.378.607 byte**. Confronto SHA-256 completo con `research/tools/Zenit/Zenit - Jackpot Latency Suite`: - -- copia precedente: 5.608 file / 2.231.427.631 byte; -- 5.578 file identici; -- 28 file modificati; -- 485 file aggiunti; -- 2 file rimossi; -- delta netto: 483 file e 1.608.950.976 byte. - -Quasi tutto il peso aggiunto è costituito da database/progetti Ghidra e risultati derivati, non da nuove funzioni utente. - -Fingerprint dei file principali analizzati: - -| File | SHA-256 | -| --- | --- | -| `app.py` | `f522aead9899fe300bf70571b6f09e68ff983bd89ca2f6c1742b5af0400e6948` | -| `IMOD-Test.py` | `31ffb4bfede24ffa6a8b15260abb40b3343791c61883c21347d144b8c0dd9c4d` | -| `Nic.ps1` | `85521e65270f664ffcd32c34cdf8a0b942f1876883e5a6ef2673dd2325d82878` | -| `WinTweakVerifier/procmon_verifier.py` | `57b3dce27073645c04253e586c8f7b1a1abe3d87e825b6880b4566c6e1635b3a` | -| `WinTweakVerifier/scripts/GhidraAnalyzer.java` | `9831f0ad3aadee99a7598c60a225d9c7ef38810ebfbcde5fa8caf08a9206ee53` | - -Il corpus applicativo Zenit non espone una licenza riutilizzabile identificata. Ghidra ha la propria licenza, ma la sua presenza non concede diritti sul codice Zenit, sui profili o sui database aggregati. - -### 5.2 Novità utili come metodo - -- Worker asincroni per operazioni di rete, restore point e merge Procmon evitano parte dei freeze UI. -- Il restore point pre-tweak è una rete di sicurezza aggiuntiva, non un rollback dei singoli valori. -- `procmon_verifier.py` associa eventi di registro riusciti al percorso completo e preserva i risultati precedenti quando un target non appare nella traccia. -- La tassonomia distingue osservazione runtime, consumer statico, table match, code reference, sola stringa e mancata osservazione. -- L’engine low-level aggiunge controlli di capacità e read-back per alcune scritture PCIe/xHCI. - -Principi da conservare: lavoro fuori dal thread UI, timeout, read-back, identità stabile, evidenza stratificata e nessun verdetto negativo da una traccia incompleta. - -### 5.3 Risultati Ghidra rilevanti - -La cartella `ghidra_results` contiene 350 JSON: 340 hanno almeno un’occorrenza, per 2.436 occorrenze complessive. Il manifest collega i risultati di rete a: - -- `tcpip.sys` versione `10.0.26100.8521`, SHA-256 `15034904b98c49b959c848f48ada109e86f6ee97ba5422ff9a6a61d848c6af39`; -- `afd.sys` versione `10.0.26100.8036`, SHA-256 `3358c34a140be8c497625d112d72a2f7209b532528e2d2869fdb5c1288c1ed42`. - -Gli hash sono stati ricontrollati sui binari locali e coincidono con `imported_manifest.json`. I risultati più rilevanti per SockTuner sono: - -| Target | Binario del corpus | Risultato statico | Conseguenza | -| --- | --- | --- | --- | -| `TcpAckFrequency` | `tcpip.sys` | `RTL_QUERY_REGISTRY_TABLE` confermata | rafforza la prova di consumo; non prova un beneficio | -| `TcpDelAckTicks` | `tcpip.sys` | `RTL_QUERY_REGISTRY_TABLE` confermata | chiude il vecchio gap “consumer non verificato” su questa build; resta Experimental/High risk | -| `FastSendDatagramThreshold` | `afd.sys` | `RTL_QUERY_REGISTRY_TABLE` confermata | prova che il nome è consumato; valore e beneficio restano non documentati | -| `DefaultReceiveWindow`, `DefaultSendWindow` | `afd.sys` | solo `TABLE_MATCH` | insufficiente per promozione | -| `MinRto`, `EnablePMTUDiscovery`, `TcpTimedWaitDelay` cercati in `tcpip.sys` | `tcpip.sys` | nessuna occorrenza nel target scelto | non è prova di non utilizzo: consumer, path o costruzione possono differire | - -`verification_report.md` e `verified_targets.json` della nuova copia sono vuoti; non è inclusa una traccia Procmon che dimostri osservazioni live. `pinned_known_good.json` contiene dichiarazioni manuali, non evidenza riproducibile. Non importare automaticamente alcun verdict. - -Conclusione concreta per SockTuner: aggiornare in futuro l’`EvidenceNote` di `TcpDelAckTicks` con la versione e l’hash sopra, mantenendo livello Experimental e rischio High finché documentazione e benchmark non stabiliscono semantica, range e vantaggio. - -### 5.4 Problemi che restano bloccanti - -- `IMOD-Test.py` tenta di disattivare la vulnerable driver blocklist e creare un servizio kernel WinRing0 con avvio automatico. -- Esegue scritture MSR/PCI/MMIO e tweak xHCI/NVMe che un read-back non rende sicuri o reversibili. -- `Nic.ps1` usa valori fissi, disabilita in massa i binding non IPv4/IPv6 e non acquisisce snapshot esatti. -- Il ramo MTU contiene un fallback logicamente incoerente; il flusso silent stampa `SUCCESS` anche quando alcune scritture sono fallite. -- L’app considera sufficiente la presenza del marker finale e può terminare brutalmente worker ancora attivi in chiusura. -- Il fallback RSS scrive direttamente il queue count nel registro quando il provider lo rifiuta. -- Profili inclusi sono specifici di una macchina/Realtek e non generalizzabili. -- Download/installazione automatica, elevazione, task pianificati e riavvii restano accoppiati a flussi senza transazione né rollback completo. - -**Verdetto:** nessuna nuova operation o valore raccomandato da importare. La sola nuova informazione di prodotto è l’evidenza statica aggiuntiva; la sola funzione candidata resta RSS tipizzato già registrato dal delta 7.0. - -## 6. Registro della pulizia - -Il 10 settembre 2026, dopo la creazione e verifica di questo documento, sono state spostate nel Cestino senza cancellazione definitiva: - -- `research/projects/`: 170 file, 159.914.579 byte; -- `research/scripts/`: 22 file, 1.473.895 byte; -- `research/tools/`: 6.126 file, 3.140.221.321 byte. - -La verifica successiva ha confermato che le tre directory non esistono più nella working tree. Restano `research/README.md`, `links/`, `notes/` e `results/`. - -Su richiesta del proprietario, anche `C:\Users\Lorenzo\Downloads\Zenit Latency Suite` è stato poi spostato nel Cestino: 6.091 file, 3.840.378.607 byte. Le informazioni necessarie sono conservate nel §5. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md deleted file mode 100644 index 916355a..0000000 --- a/docs/ROADMAP.md +++ /dev/null @@ -1,270 +0,0 @@ -# SockTuner Delivery Roadmap - -SockTuner is built in small, testable increments. A step is complete only when its exit criteria pass; unfinished work is not hidden behind a polished screen. - -## Priorities - -| Priority | Meaning | -| --- | --- | -| **P0** | Required for a trustworthy usable core; blocks writable features | -| **P1** | Required for private beta and controlled tuning | -| **P2** | Release hardening or valuable follow-up work | - -## Safety gates - -These apply to every step: - -- Production uses native Windows/.NET APIs first and has no PowerShell runtime dependency. -- Material under `research/` is reference-only: never executed, bundled, or copied without validation and license review. -- Read-only inventory and diagnostics run unelevated where Windows permits. -- Every writable setting needs an allowlisted type, exact target, validation, snapshot, read-back verification, and exact rollback. -- Real writes are tested only in an explicitly prepared disposable VM. Default tests use fakes. -- The UI remains write-locked until the complete low-risk transaction path passes its VM gate. - -## Execution order - -### Step 1 — Complete shell and inventory integrity (`0.1`) — **P0, complete** - -**Goal:** finish the dark Windows desktop shell and make adapter/driver discovery reliable enough to support later diagnostics and plans. - -Deliverables: - -- Complete dark Metro/Aero2 treatment for the window, title bar, navigation, cards, inputs, grids, selection, focus, disabled states, scrollbars, and dialogs. -- Embed the SockTuner application icon in the window and executable. -- Inventory OS, CPU, adapters, stable interface GUIDs, addresses, gateways, DNS, link state/speed, driver identity/version, and driver-advertised NDIS properties. -- Distinguish supported, unsupported, unavailable, and partial inventory instead of reporting an empty result as success. -- Add refresh, adapter/property filtering, copy, and visible per-surface errors. -- Keep all discovery read-only and localization-resilient. - -Exit criteria: - -- No unintended light surfaces remain in the dark theme at 100%, 125%, 150%, or 200% DPI. -- Keyboard focus and normal text meet contrast requirements. -- Physical, virtual, disconnected, and unsupported adapters are identified without hard-coded adapter names. -- Supported Intel/Realtek adapters expose raw NDIS keywords, current values, defaults, and driver-advertised ranges/enums. -- Build, format, tests, and supervisor gate pass. - -### Step 2 — Complete read-only Windows network inventory (`0.2`) — **P0, complete** - -**Goal:** show the actual Windows network state before adding more tests or any writes. - -Deliverables: - -- Active routes, default route, interface metrics, IPv4/IPv6 MTU, network profiles, and DNS configuration. -- TCP global/template state, RSS/RSC/offload state, bindings, QoS policy inventory, Winsock providers, and relevant NIC/link counters. -- Search/filter across inventory and copy selected values. -- Versioned JSON snapshot export and redacted support snapshot. -- Structured local application log with bounded retention and an **Export logs** action. - -Exit criteria: - -- Exported data matches the visible snapshot and carries schema/tool versions and capture time. -- Sensitive identifiers are explicitly included or redacted by the user, never silently leaked. -- Errors identify the failed surface and do not discard successful inventory from other surfaces. -- English and Italian Windows validation finds no dependency on localized property labels. - -### Step 3 — Diagnostic and monitoring workbench (`0.3`) — **P0, complete** - -**Goal:** turn the current short diagnostic into a complete, observable test workflow. - -Deliverables: - -- Configurable quick, standard, and extended test profiles. -- Concurrent timestamped probes to gateway, neutral reference, custom/game endpoint, and first reachable ISP boundary when discoverable. -- Sent/received/lost, minimum, median, average, P95, P99, maximum, named jitter, and spike timeline. -- DNS timing, optional TCP connection timing, repeated route sampling, path-MTU discovery, and NIC counter deltas. -- Continuous read-only monitoring with explicit start/stop, duration, interval, cancellation, and bounded in-memory samples. -- Clear states for timeout, blocked/deprioritized ICMP, DNS failure, route failure, refusal, cancellation, and local API failure. - -Exit criteria: - -- Deterministic fixtures test every calculation and classification. -- No network test starts automatically or generates uncontrolled traffic. -- Intermediate-hop ICMP behavior is not mislabeled as end-to-end loss. -- Monitoring can run and stop repeatedly without leaking tasks, sockets, or memory. - -### Step 4 — Reports, history, and comparison (`0.4`) — **P0, complete** - -**Goal:** make observations reproducible and useful for before/after analysis or support escalation. - -Deliverables: - -- Versioned JSON and self-contained offline HTML diagnostic reports. -- Raw sample export, run metadata, targets, intervals, route samples, load conditions, and calculation method. -- Local run history with bounded retention, delete, redaction, and export. -- Baseline/post-change comparison using identical test parameters. -- Multi-run metric trends and a redacted ISP/support evidence report. - -Exit criteria: - -- Reports render without a CDN or internet connection. -- Imported SockTuner reports are schema-validated and never execute content. -- “Improvement” is shown only for valid comparable runs. - -### Step 5 — Transaction engine and write preview (`0.5`) — **P0, complete** - -**Goal:** connect the existing typed transaction core to a safe plan UI without enabling uncontrolled writes. - -Deliverables: - -- Change cart with selected adapter, current value, proposed value, source, evidence, risk, trade-off, and restart requirement. -- Dry-run diff, stale-plan rejection, deterministic ordering, exact snapshot, read-back verification, audit history, and rollback preview. -- Same signed executable elevated-worker mode accepting only versioned typed operations. -- Strict operation and registry-address allowlists; no executable paths, scripts, shell fragments, or arbitrary registry paths in plans. -- In-memory failure injection for partial apply, verification failure, cancellation boundaries, external drift, and rollback failure. - -Exit criteria: - -- The UI cannot bypass the transaction service or create an unlisted operation. -- Default and CI tests cannot mutate the host. -- The complete fake-backed path passes: - -```text -read → plan → snapshot → apply → verify → rollback → verify original state -``` - -- The production write backend remains unavailable until Step 6 VM validation passes. - -### Step 6 — First writable settings in a disposable VM (`0.6`) — **P1, complete** - -**Goal:** prove a very small end-to-end writable surface before expanding coverage. - -Deliverables: - -- Select a few documented, exactly reversible, low-disruption settings. -- Re-detect machine, adapter, driver, capability, and current value after UAC. -- Apply, verify, persist audit state, roll back, and verify the original value. -- Recovery behavior for interruption, stale values, access denied, target disappearance, and pending restart. -- Explicit VM-only operator gate and documented recovery path. - -Exit criteria: - -- Every supported setting passes repeated read/apply/read/rollback/read testing on disposable Windows 10/11 VMs. -- External drift is refused rather than overwritten. -- No adapter restart, reboot, or connectivity interruption occurs without explicit preview and confirmation. - -### Step 7 — NIC and driver controls (`0.7`) — **P1, current (7a complete, 7b in alpha)** - -**Goal:** expose only capabilities actually advertised by the selected driver. - -Step 7 is split into two gates: - -- **7a — capability collection (no disposable hardware required):** the in-app compatibility-report flow captures a privacy-safe inventory from collaborator PCs with real NICs and opens a dedicated GitHub issue form. All current setting values, persistent adapter/PNP identifiers, addresses, paths, machine name, and exact timestamps are omitted; adapter model, driver version, NDIS keywords, defaults, ranges and enums seed the capability matrix and fake-platform fixtures. -- **7b — write unlock (alpha):** NIC/driver writes are enabled behind versioned in-app consent, UAC elevation, driver-advertised validation re-read inside the elevated worker, and a typed confirmation for high-risk or experimental changes. The static per-setting allowlist is retained for registry-backed catalog entries only; for NIC properties the driver's own advertised constraints are the allowlist, so an unsupported keyword or value cannot be planned or written. Capability coverage is currently Intel I226-V and Wireless-AC 3168, Realtek RTL8125 and 8852CE, and MediaTek MT7925 — keywords outside that corpus are exposed but reported as high risk and uncharacterised. - -Deliverables: - -- RSS, moderation, flow control, buffers/queues, supported offloads, jumbo frames, EEE, power, wake, and link controls. -- Driver enum/range validation and absent/unsupported-state handling. -- A refusal list for keywords that are unsafe at any value (`NicKeywordCatalog` `Rejected` → evidence level `Blocked`): the undocumented Realtek `HwOption*` bitmasks, `ThreadPoll`, `DisablePhyReset`, `PnPCapabilities`, and `DropHighlyFragmentedPacket`. They stay visible in the read-only inventory with the reason attached, and `AdapterSettingCapability.Validate` refuses them inside the elevated worker. -- Adapter restart planning, reconnection verification, and exact rollback. -- Transparent **Balanced**, **Low latency**, and **Custom** proposal profiles for validated hardware only. - -Exit criteria: - -- No missing driver property is created or guessed. -- Profiles remain editable diffs and touch only the selected adapter. -- Intel I219/I225/I226 and Realtek RTL8111/RTL8125-class validation records expected trade-offs and failures. - -### Step 8 — TCP/IP, interfaces, QoS, and Winsock (`0.8`) — **P1, complete** - -**Goal:** expand controlled writes beyond NIC properties without introducing broad reset behavior. - -Deliverables: - -- Supported TCP global/template controls, selected interface settings, MTU, metrics, DNS, and QoS policy editing. -- Carefully scoped TCP ACK/Nagle controls with TCP-only and experimental warnings. -- Winsock inspection and separately gated targeted repair workflows. -- Remote-session and connectivity-disruption warnings. - -Exit criteria: - -- Capability gates use the active Windows surface, not OS-name guesses. -- IPv6, bindings, and hidden adapters are never blanket-disabled. -- Rollback restores exact captured state; broad resets are not presented as rollback. - -### Step 9 — Gaming root-cause analysis (`0.9`) — **P1, complete** - -**Goal:** correlate inventory, counters, routes, and measurements into evidence-ranked findings. - -Deliverables: - -- Guided game/region profiles and direct endpoint input. -- Candidate causes across PC/NIC, LAN/Wi-Fi, router/access link, ISP, routing/peering, region, and remote endpoint. -- Supporting and contradicting observations plus confidence and ownership of the fix. -- Controlled loaded-latency testing with an explicitly selected endpoint. -- Local proposals only when SockTuner controls the observed cause; otherwise router/ISP/region guidance. - -Exit criteria: - -- **Inconclusive** remains a valid result. -- DNS is not blamed for steady in-session RTT without endpoint-selection evidence. -- TCP-only changes are not presented as generic UDP game optimizations. - -### Step 10 — Private beta and `1.0` (`0.9.x` → `1.0`) — **P2** - -Deliverables: - -- Windows 10 22H2 and supported Windows 11 matrix testing at multiple DPI levels and English/Italian locales. -- Accessibility, performance, long-run stability, elevated-worker threat model, recovery drills, and privacy review. -- Signed installer/update path, SBOM, license, vulnerability policy, support documentation, and release checklist. -- Remove private captures, nested repositories, external binaries, archives, and unknown-license material from release inputs. - -Exit criteria: - -- No critical privilege-boundary, rollback, data-loss, or connectivity-recovery defects. -- All distributed files have known provenance and valid licenses. -- Signed builds install, update, repair, and uninstall cleanly. - -## Current queue - -The queue defines completion gates. A read-only prerequisite from the next item may land in the same reviewed increment, but no step is marked complete and no writable scope unlocks until every earlier exit criterion passes. - -1. **P1 / Step 7b:** broaden real-hardware validation of capability-advertised NIC and driver controls, and grow the characterised-keyword corpus as more compatibility reports arrive. -2. **P2 / Step 10:** the gates that need what this project does not yet have — a code-signing certificate, and real machines across the Windows and locale matrix. Listed below rather than left implicit, because none of them can be closed by writing code. - -Steps 8 and 9 are complete. Step 8 closed with three things rather than a large surface. The interface metric joined MTU as a per-interface override whose restore is the *removal* of the value, since absent means Windows derives the metric from link speed — writing a number back would be a different setting that happened to match, not a rollback. A remote-session guard now stands in front of every change that drops the link: it does not work out which adapter carries the session, so it assumes this one might and forces the typed confirmation, because being wrong in that direction costs a sentence and being wrong in the other direction costs the machine. An unrecognised restart requirement is treated as disruptive, and a test fails if one appears that nobody classified. - -The third is a refusal. `netsh winsock reset` is the repair every guide reaches for, and it is now declined on the record: it rebuilds the catalog from defaults rather than restoring what was there, so nothing it does can be rolled back — which is the one thing this project will not ship. What made it famous were third-party layered service providers, deprecated in Windows 8 and not loaded by current builds; the catalog on a Windows 10 or 11 machine holds Microsoft providers, so SockTuner shows it and leaves it alone. Step 8's exit criteria about blanket-disabling IPv6 or bindings, and about broad resets not being presented as rollback, are now held by tests rather than by nobody having added one. - -Step 9's exit criteria were already met and are covered: **Inconclusive** is a real result in the bottleneck locator, the loaded-latency grader and path-MTU discovery; DNS is never blamed for steady in-session RTT, and says so in the finding itself; and the TCP-only settings state plainly that they do nothing for UDP. Regional endpoint catalogues are deliberately not bundled — they are third-party addresses that change without notice, and an imported capture supplies the real one. - -Step 10 cannot be completed from a keyboard. What remains needs a code-signing certificate (signed installer, update path, and the end of the SmartScreen prompt), real machines for the Windows 10 22H2 and Windows 11 matrix at several DPI levels in English and Italian, a screen-reader pass, a long-run stability soak, and recovery drills on disposable VMs. An SBOM is deliberately deferred to that same work rather than added to a release pipeline that is currently green. - -The Group Policy QoS Packet Scheduler limits are catalogued: reservable bandwidth and the outstanding-packet limit, both verified present in `pacer.sys`. The third policy in that node, timer resolution, is recorded as inert instead — `pacer.sys` contains neither the string nor any sign of reading it, while it does contain the other two. - -Parity with SG TCP Optimizer is deliberate rather than total. Most of its surface is already covered by the CIM TCP provider and the NIC keyword path; the rest is declined on the record in `InertSettingCatalog`, which now cites the System32 evidence behind each decline — including that the widely copied `HostPriority` spelling appears nowhere in `mswsock.dll`, whose actual value is `HostsPriority`. - -A DNS resolver benchmark queries each candidate directly over UDP so resolvers this machine does not use can still be measured, ranks them by median lookup time, and refuses to call a sub-5 ms difference an improvement. The fastest one can be applied to a chosen adapter through `SetInterfaceDnsSettings`, as a typed setting the transaction engine snapshots, verifies and rolls back like any other; restoring DHCP-assigned resolvers is an explicit state rather than a deletion. An opt-in tick applies a winner automatically, using the same noise floor as the verdict so it cannot churn on run-to-run variation. - -Capture reports produced by an external analyzer can be imported. The value of one is the single thing SockTuner cannot work out by itself — which server the game actually talked to, and how its packets were spaced — so the import supplies the endpoint and SockTuner then measures it directly rather than trusting the numbers. Flow quality is judged against the game's own tick rate rather than a fixed threshold, since the same jitter figure means different things on a 20 ms and a 50 ms tick. The file is treated as untrusted input: size-limited, parsed defensively, never executed and never turned into a path. - -The health check also reports running kernel-level anti-cheat services, so an adapter or driver change is not applied mid-session and later mistaken for something else. - -Device interrupt affinity is exposed as its own typed setting: which processors service a device's interrupts, across all device classes rather than only network ones, since the device competing with the NIC for a core is usually not another NIC. The mechanism is the documented policy under each device's own `Enum` key, and `pci.sys` contains every value name it uses. Automatic placement is deliberately not offered — there is no generally correct one — so the app shows what Windows currently has, validates a chosen placement against the processors that exist, warns about CPU 0 and about stacking devices on one core, and makes restoring the Windows default a first-class action. - -The research corpus under `research/` has been audited against the product rather than imported: its NDIS keyword work, `netsh int tcp` settings, MTU probing, Nagle and power-saving tweaks are all already covered by the tuning plan, the CIM TCP provider and the diagnostics. What it turned up that was genuinely missing is the port-reuse range the provider advertises and the app did not expose, and the interrupt affinity work above. A short list of external references — the Microsoft documentation behind each surface, and the tools SockTuner does not replace — is linked from Preferences; nothing is bundled or downloaded. - -A health check runs on every inventory refresh: it reads the state Windows already reported and names what it can see — a driver years out of date, a gigabit-class adapter negotiated at 100 Mbit/s, link power saving on the adapter carrying the traffic, local and public resolvers mixed on one interface, wired and wireless both holding a gateway, capture or virtualisation filters bound to the datapath, and offloads someone disabled and forgot. Each finding carries its evidence, what to do, and the tab that acts on it, so the first screen routes into the rest of the app instead of being a dead end. It measures nothing and changes nothing. - -Every service in the codebase is now reachable from the UI. Measurement (throughput, loaded latency), diagnosis (bufferbloat grade, bottleneck location, NAT topology, stability episodes, Wi-Fi radio, baseline drift, live watchdog) and remediation (per-finding actions, use-case profiles, receive-window advice, router guidance) each have a surface, and remediation hands proposed changes to the tuning plan rather than applying anything itself. The header badge reports the real write state — `INVENTORY ONLY` until the change consent is accepted, `CHANGES ARMED` after — instead of the permanent `READ-ONLY PREVIEW` label, which stopped being true once Step 7b unlocked the transaction path. - -Writable surfaces: the twelve registry-backed catalog entries (three experimental TCP-ACK behind typed confirmation, four MMCSS, interface MTU, NetBIOS over TCP/IP, TIME_WAIT delay, two DNS cache caps) and every property the selected driver advertises, minus the keywords the catalog rejects outright. Nothing is written that the driver does not currently advertise for that adapter. - -A measurement now carries the cadence it should be read against. A game server does not process input continuously: it advances the world in fixed steps, and that rate decides what a given number costs. Five milliseconds of jitter is a rounding error against a 50 ms update and is most of the budget against a 7.8 ms one, so the jitter limits are derived from the selected tick rate rather than chosen — half a tick is comfortable, one tick is the edge — and both are capped at 15 ms and 30 ms, because the tick arithmetic alone would call 90 ms of jitter fine on a 10 Hz game, which is true of the tick and useless to a person. The latency limits tighten with the tick rate and are labelled as the judgement they are. The loss limits are neither derived nor scaled: a dropped packet is a dropped input at every tick rate. The verdict is the worst of the three, never their average, and the metric that decided it is named so it can be checked against the table. - -`GameProfiles` states where each tick rate came from — developer-stated, community-reported, or a band that deliberately does not claim a title. A rate matched from an imported capture never snaps to a generic band, because that would put a game's name on a capture that never carried one; an unmatched rate is added as its own entry instead. The tick rate is what SockTuner judges against and deliberately not what it sends at: a serial ICMP probe cannot reach 128 packets a second against a real path, and sending at a game's rate to somebody else's server uninvited is not this app's business. What the game does set is the size of each probe, since a live game packet is not the 32 bytes a default ping carries. - -Two measurement details follow from that. Jitter is now also reported over fixed one-second windows — the standard deviation inside each second, averaged — because the existing consecutive-difference figure moves with how fast the profile sent, and a threshold derived from a tick rate needs a figure that does not. It is blank rather than fabricated when no second collected two replies. And a monitoring run reports availability as a share of *time*, taken from the worst target rather than summed across them: a line that answers 99.98 % of probes but goes silent for four seconds twice an evening is the exact fault a game notices and a packet average hides. Its resolution is the probe interval, which the report says rather than implies — as it says that Windows reports an ICMP round trip in whole milliseconds, which at 128 Hz is a noticeable share of the budget being judged. - -Two capabilities from the same measurement sites are declined on the record. A percentile against other people's tests needs a stored corpus and therefore a backend, which this project does not have and does not want. A "your server is 542 km away, so 5.4 ms of your ping is light in fibre" line needs the endpoint geolocated by a third-party service, and what it concludes — that the rest is equipment — the bottleneck locator already establishes from the path itself, without the dependency. Blocking a game's datacenters at the firewall, as FAST GeoFence does, is declined for a different reason: it is a per-title change that buys a better server with failed queues, and it is not a network fault being fixed. - -Every catalog entry carries an `EvidenceNote` recording what actually backs its evidence level — the Microsoft documentation, or the Windows component observed to consume the value (`tcpipreg.sys` for the TCP-ACK and TIME_WAIT entries, `dnsrslvr.dll`/`dnsapi.dll` for the DNS caps, `avrt.dll` and `mmcss.sys` for MMCSS). Two entries state plainly that nothing has been verified: `TCPNoDelay` and `TcpDelAckTicks`. A test refuses any entry without a note, and refuses either of those two claiming the Documented level. - -## Deferred until measured demand - -- ETW process-to-endpoint correlation and optional PCAP import. -- Additional loaded-latency/throughput service integrations. -- Wi-Fi radio/roaming controls and additional NIC validation packs. -- CLI automation, signed profile exchange, ARM64, enterprise deployment. -- A custom capture driver, permanent service, plugin marketplace, or cloud platform; each requires a separate security and architecture review. diff --git a/docs/assets/banner.svg b/docs/assets/banner.svg deleted file mode 100644 index 7753f61..0000000 --- a/docs/assets/banner.svg +++ /dev/null @@ -1,114 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - SockTuner - ADVANCED NETWORK TUNING & DIAGNOSTICS FOR WINDOWS - - - - - ALPHA - - diff --git a/research/README.md b/research/README.md index 3523792..120ed4c 100644 --- a/research/README.md +++ b/research/README.md @@ -1,13 +1,3 @@ -# Private Research Material +# Research policy -Il corpus originale è stato analizzato staticamente. Inventario, provenienza, conclusioni e registro della pulizia sono conservati in [`docs/RESEARCH_ARCHIVE.md`](../docs/RESEARCH_ARCHIVE.md). - -Il 10 settembre 2026 le directory voluminose `projects/`, `scripts/` e `tools/` sono state spostate nel Cestino, senza cancellazione definitiva. Restano soltanto: - -| Directory | Contenuto | -| --- | --- | -| `notes/` | Note originali, non validate | -| `links/` | Collegamenti e provenienza | -| `results/` | Risultati personali leggeri, non benchmark generalizzabili | - -Nessun elemento residuo è automaticamente corretto, sicuro, licenziato per la redistribuzione o adatto al codice di produzione. Non eseguire comandi remoti o applicare tweak dalle note; usare soltanto le conclusioni indipendenti registrate nella documentazione del progetto. +Third-party research material is not distributed with SockTuner. Production behavior must be supported by documented Windows interfaces, driver-advertised capabilities, repeatable tests, and exact rollback. diff --git a/tests/SockTuner.Tests/RejectedKeywordTests.cs b/tests/SockTuner.Tests/RejectedKeywordTests.cs index 2060871..c092367 100644 --- a/tests/SockTuner.Tests/RejectedKeywordTests.cs +++ b/tests/SockTuner.Tests/RejectedKeywordTests.cs @@ -9,7 +9,7 @@ namespace SockTuner.Tests; /// public sealed class RejectedKeywordTests { - // Distilled from docs/JACKPOTS_ZENIT_NDIS_CANDIDATES.md §C. + // Unsafe low-level driver controls stay denied even when advertised. public static TheoryData Rejected => [ "HwOption", "HwOptionV2", "HwOptionV3",