This repository has been archived on 2026-09-16. You can view files and clone it, but cannot push or open issues or pull requests.
win-diagnostics-analysis/docs/migration-inventory.md

234 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Legacy diagnostics inventory and first contract decisions
## Source and scope
Inspected 2026-09-15 at pinned revisions:
- WinDiagnostics: `1de4d425ecca3a97bcbffd4c8b5ebec464810ac8`.
- typst_reporter: `1d381904fff3d378a7c0e04588e75310a9b7ed60`.
This inventories the collector and normalization/analysis source for the initial
offline migration slice. It records existing behavior, not an endorsement of
medical, security, or vendor remediation advice. External advisory URLs have not
been revalidated; advisory review remains required before rule publication.
## Collection boundary
The collector requires PowerShell 5.1 or later and native Windows APIs. It uses
CIM, registry, event logs, storage/Defender cmdlets, and native Windows commands.
Some APIs may be unavailable; elevated checks include storage reliability,
DISM `/CheckHealth`, and SFC `/verifyonly`. It writes JSON and temporary probe/SFC
files; it does not run repair commands. Native behavior has not been executed on
this Linux host (PowerShell is unavailable).
`-Compact`, `-Mid`, and `-Full` are mutually exclusive; omitted means Full.
`-OutputDirectory` defaults to writable Documents, then TEMP. Output filenames
contain hostname and collection timestamp; the script returns the saved path.
`-EventLogDays` defaults to 7 (1–3650), `-MaxEventErrors` to 100 (1–5000), and
`-JsonDepth` to 12 (3–100). Output is UTF-8 without BOM, capture schema 2.
The capture envelope is `schema_version`, `report_type`, `mode`, `generated_at`,
`completed_at`, `host`, `parameters`, `warnings`, `summary`, and `sections`.
Full adds `diagnostic_collection`. Section envelopes contain `status`, `count`,
`data`, and `error`; event sections additionally record `limit` and `truncated`.
Native command records retain executable, arguments, exit code, and output.
### Collector function inventory
All functions below belong to win-diagnostics; retain implementation provenance
and separate collection plumbing from normalization/analysis during extraction.
- `Test-IsAdministrator`
- `Test-DirectoryWritable`
- `Get-InstalledPrograms`
- `Get-StartupRegistryEntries`
- `Get-ProblemDevices`
- `Invoke-ReportSection`
- `New-SkippedSection`
- `New-UnavailableSection`
- `Get-StorageReport`
- `Get-DefenderReport`
- `Invoke-NativeCommand`
`Get-CompactData` is nested in Compact mode. The top-level mode branches populate
sections and summary; these are substantial collection logic, not just CLI glue.
### Typst normalizer function inventory
- `get`
- `value-text`
- `enabled`
- `legacy-incomplete`
- `first`
- `section`
- `section-data`
- `section-first`
- `section-count`
- `section-status`
- `number`
- `bool-text`
- `is-leap-year`
- `date-index`
- `datetime-day`
- `datetime-second`
- `display-time`
- `display-date`
- `fade-weight`
- `event-rule`
- `capture`
- `event-summary`
- `event-sections`
- `windows-level`
- `raw-events`
- `group-events`
- `catalog-correlation`
- `command-output`
- `object-lines`
- `watchlist-catalog`
- `watch-matches`
- `watchlist-findings`
- `reliability-events`
- `normalize`
Classification:
- Evidence access/conversion: `get`, `first`, `section*`, `number`, `enabled`,
`legacy-incomplete`, `command-output`, `raw-events`, `event-sections`,
`reliability-events`, and date parsing belong to win-diagnostics.
- Rules: `fade-weight`, `event-rule`, `group-events`, `catalog-correlation`,
`watch-matches`, and matching in `watchlist-findings` belong to win-diagnostics.
- Presentation: `value-text`, `bool-text`, `display-time`, `display-date`,
`windows-level`, `event-summary`, and `object-lines` must be split: retain typed
facts in diagnostics; move report-facing formatting into the report adapter.
- `normalize` combines all three concerns. Its technical findings and evidence
coverage belong here; health headline prose, display inventory/excerpts, and
report-ready remediation belong to beffroi-reports. Generic display widgets
belong to Reportist. Do not port the entire function as the public interface.
- Helpers `capture`, `is-leap-year`, `date-index`, and `watchlist-catalog` support
their owning normalization/rule operation; no runtime Typst/YAML imports should
remain in the diagnostic engine merely to reproduce legacy implementation.
## Rule-by-rule ownership
All provider/ID matchers below describe generic technical events. Diagnostic
matching, evidence, severity, confidence, and any fading stay in win-diagnostics.
Report-ready `remediation`, `resolution_steps`, and recipient-facing recommendations
move to the adapter/content layer. Preserve rationale/reference provenance for
review; event IDs alone must not become unsupported root-cause claims.
| Provider | ID | Existing severity | Fading | Owner |
| --- | --- | --- | --- | --- |
| Microsoft-Windows-WER-SystemErrorReporting | 1001 | critical | no | win-diagnostics |
| volmgr | 162 | info | no | win-diagnostics |
| stornvme | 11 | critical | no | win-diagnostics |
| Microsoft-Windows-TPM-WMI | 1040 | critical | no | win-diagnostics |
| Service Control Manager | 7000 | warning | yes | win-diagnostics |
| Service Control Manager | 7009 | warning | yes | win-diagnostics |
| Microsoft-Windows-NDIS | 10317 | warning | no | win-diagnostics |
| Application Error | 1000 | warning | yes | win-diagnostics |
| Microsoft-Windows-WindowsUpdateClient | 20 | warning | yes | win-diagnostics |
| Application Hang | 1002 | warning | yes | win-diagnostics |
| MsiInstaller | 1043 | warning | yes | win-diagnostics |
| Volsnap | 36 | warning | no | win-diagnostics |
| Service Control Manager | 7043 | warning | yes | win-diagnostics |
| Microsoft-Windows-DistributedCOM | 10010 | info | no | win-diagnostics |
| EventLog | 6008 | warning | no | win-diagnostics |
| Service Control Manager | 7023 | warning | yes | win-diagnostics |
| MsiInstaller | 11704 | warning | yes | win-diagnostics |
| MsiInstaller | 11722 | warning | yes | win-diagnostics |
| VSS | 12344 | warning | no | win-diagnostics |
| .NET Runtime | 1022 | info | no | win-diagnostics |
| Waterfox Default Browser Agent | 5 | info | no | win-diagnostics |
| Microsoft-Windows-Kernel-Boot | 29 | warning | no | win-diagnostics |
| Service Control Manager | 7031 | warning | no | win-diagnostics |
| Microsoft-Windows-DeviceAssociationService | 3505 | warning | no | win-diagnostics |
| Microsoft-Windows-HAL | 15 | warning | no | win-diagnostics |
| Microsoft-Windows-HAL | 21 | warning | no | win-diagnostics |
| usbaudio2 | 38 | warning | no | win-diagnostics |
| ESENT | 419 | critical | no | win-diagnostics |
| ESENT | 474 | critical | no | win-diagnostics |
| ESENT | 907 | critical | no | win-diagnostics |
| ESENT | 908 | critical | no | win-diagnostics |
| Microsoft-Windows-Defrag | 264 | warning | no | win-diagnostics |
| Microsoft-Windows-WLAN-AutoConfig | 10002 | info | no | win-diagnostics |
| Microsoft-Windows-DistributedCOM | 10016 | info | no | win-diagnostics |
| Netwtw10 | 6062 | info | no | win-diagnostics |
| Microsoft-Windows-Hyper-V-Hypervisor | 167 | warning | no | win-diagnostics |
| volmgr | 161 | warning | no | win-diagnostics |
| Microsoft-Windows-WinRM | 10149 | info | no | win-diagnostics |
| winsrvext | 100 | info | no | win-diagnostics |
| Netwtw10 | 5005 | warning | no | win-diagnostics |
| Netwtw10 | 5032 | warning | no | win-diagnostics |
| Netwtw10 | 5002 | warning | no | win-diagnostics |
| Netwtw10 | 5010 | warning | no | win-diagnostics |
| Microsoft-Windows-Perflib | 1008 | warning | no | win-diagnostics |
| Microsoft-Windows-WMI | 63 | info | no | win-diagnostics |
| Microsoft-Windows-Winlogon | 6004 | warning | no | win-diagnostics |
| Microsoft-Windows-RestartManager | 10010 | info | no | win-diagnostics |
| Microsoft-Windows-Search | 10024 | warning | no | win-diagnostics |
| Microsoft-Windows-CodeIntegrity | 3116 | info | no | win-diagnostics |
| Microsoft-Windows-CodeIntegrity | 3099 | info | no | win-diagnostics |
| Microsoft-Windows-CodeIntegrity | 3085 | info | no | win-diagnostics |
| Microsoft-Windows-CodeIntegrity | 3076 | warning | no | win-diagnostics |
| Microsoft-Windows-CodeIntegrity | 3077 | warning | no | win-diagnostics |
Unknown events remain `unanalysed`. The normalizer also implements device status,
DISM/SFC text interpretation, disk headroom/health, firewall state, unsigned-driver
signals, coverage gaps, and catalog event correlation outside the YAML catalog.
These require individual regression cases before extraction is complete.
### Watchlist entries
| Entry | Matcher owner | Report content owner | Caveat |
| --- | --- | --- | --- |
| `winring0` | win-diagnostics | beffroi-reports | Candidate/advisory; retain evidence and matching prerequisites. |
| `dell-dbutil` | win-diagnostics | beffroi-reports | Candidate/advisory; retain evidence and matching prerequisites. |
| `gigabyte-oc-guru` | win-diagnostics | beffroi-reports | Candidate/advisory; retain evidence and matching prerequisites. |
| `intel-wifi-observed` | win-diagnostics | beffroi-reports | Separate capture-specific adapter context. |
| `obs-overlay` | win-diagnostics | beffroi-reports | Candidate/advisory; retain evidence and matching prerequisites. |
| `obs-audio-hooks` | win-diagnostics | beffroi-reports | Candidate/advisory; retain evidence and matching prerequisites. |
| `smb1` | win-diagnostics | beffroi-reports | Candidate/advisory; retain evidence and matching prerequisites. |
The catalog has seven generic candidate matchers, not private incident IDs.
Vendor-specific matching is not inherently organisation-specific. The
`intel-wifi-observed` prose contains capture-specific AX200/AX210 context; retain
that context in beffroi-reports rather than a generic diagnostic title. All
matches need their limitations preserved; zero-weight advisories must not become
confirmed failures or silently alter health scoring.
## First diagnostic contract decisions
1. Keep the raw capture schema version distinct from the new diagnostic schema
version. A schema-2 capture does not imply diagnostic contract version 2.
2. Preserve the raw capture as an input artifact; observations reference its
relative artifact path and JSON Pointer. Findings reference observation IDs.
3. Use typed values and explicit collection state. Do not use `"Unavailable"`,
`"Yes"`, or formatted prose as substitutes for typed values/status fields.
4. Findings carry stable IDs, severity, confidence, title, technical description,
and evidence references. Keep recommendations and executive summaries out.
5. Retain unsupported/unknown events and partial collection. A missing section
cannot establish health. Define how summary-only captures differ from records.
6. Use collection time as the explicit analysis reference time; never use wall
clock time implicitly for fading. Document rounding/timezone compatibility.
The version-1 schema and standalone validator are now implemented; see
[diagnostic contract](diagnostic-contract.md). Offline normalization and native
collection remain unimplemented; full Windows support is a later validation gate.
## Provenance and fixture review
The five files in `tests/fixtures/legacy/` are copied unchanged from
`typst_reporter/tools/fixtures/` at the revision above. Their accompanying MIT
notice is retained. All string values were reviewed: hostnames/users are explicit
TEST/SYNTHETIC/CI placeholders, device identities are synthetic, paths are generic
Windows/driver paths, and software names are intentional rule inputs. No real
incident capture, hostname, serial number, account, IP, or network identifier was
imported. This review applies to these five files only.
`tests/legacy-baseline.json` records observed legacy output for comparison; it is
not the new diagnostic schema or proof that legacy conclusions are correct.
The macro repository's `scripts/check-legacy-baseline.py` reproduces it using the
pinned legacy source in a temporary directory. Fixtures remain independently
usable by future component tests; this migration-only baseline runner is not a
component runtime dependency.