8.1 KiB
Diagnostic contract version 1
The implemented public interface is diagnostic.schema.json, a JSON Schema Draft 2020-12 document. This pass provides validation and synthetic examples, not a migrated collector or analysis engine.
Install and validate independently
Bash and jq are required at runtime. From a standalone component checkout:
make validate INPUT=examples/diagnostic.json
make validate INPUT=examples/diagnostic.json EVIDENCE_ROOT=tests/fixtures/legacy
make test
The test target creates a uv-managed Python environment and synchronizes the
pinned test dependencies from requirements.txt.
No Typst, Reportist, macro checkout, network service, or live Windows machine is
needed after dependencies are installed. Validation accepts an explicit JSON path,
writes no artifacts, and exits 0 for valid input, 1 for invalid/unreadable input or
missing dependencies, and 2 for incorrect CLI usage. Errors identify JSON paths.
Envelope
| Field | Meaning |
|---|---|
schema_version |
Exactly integer 1, the diagnostic artifact contract version. |
metadata.producer |
Tool name and version/revision; synthetic examples label their producer version accordingly. |
metadata.collected_at |
RFC 3339 collection timestamp with timezone. |
metadata.analysis_reference_time |
Explicit RFC 3339 reference for time-dependent analysis; never implicitly today's date. |
metadata.source |
Original capture artifact, its SHA-256, and its separate capture schema_version (1 or 2). |
system |
Sparse typed JSON system facts. Unknown facts should be omitted or null, not presentation strings. |
collection |
Capture mode, coverage status, and named section results. |
observations |
Identified raw JSON values with source pointers and section names. |
findings |
Identified technical conclusions with severity, confidence, description, and observation IDs. |
warnings |
Nonblank diagnostic/collection limitation strings. |
All envelope fields are required. Most objects reject unknown fields to catch
misspellings; system intentionally allows heterogeneous JSON facts. JSON object
keys must be unique and numbers finite. References are local to the schema;
validation performs no remote schema lookup.
Collection semantics
Modes are Compact, Mid, and Full. Coverage status is complete, partial,
or unknown. Each declared section has status (ok, skipped, unavailable,
missing), record_count (nonnegative integer or null), and truncated (boolean).
A non-OK section requires a reason. Count is retained-record count, not a health
signal; failed native commands may still provide records worth preserving.
The validator rejects complete with no declared sections, unsuccessful sections,
or truncation. Complete means complete for the declared analysis scope, not proof
of Windows health or a claim that every possible collector section was evaluated.
A future analyzer must declare its actual scope honestly. Null counts and absent
facts cannot establish health; successful zero-count and missing zero-count checks
must remain distinguishable.
Evidence and finding identity
An observation has id, section, source_pointer, and value; optional
observed_at is a timezone-qualified timestamp. Its value is the exact raw JSON
value at that pointer, not a rewritten prose excerpt. Derived/normalized facts
belong in system or a finding's technical description, supported by observations.
JSON Pointers escape ~ as ~0 and / as ~1; the empty pointer names the root.
A finding has id, severity (critical, warning, info, unanalysed),
confidence (number 0–100), title, description, and a nonempty evidence list
of observation IDs. Optional age_days and relevance_weight (0.5–1) preserve
the migrated rule catalog's time-fading behavior without changing the underlying
technical confidence. Confidence describes strength of the finding, not the chance
that the system is healthy. IDs are opaque tokens; producers must keep them stable
for repeated analysis of the same evidence/rule. The future analyzer must document
its ID derivation. The validator rejects duplicate IDs and dangling observation
or section references; JSON Schema alone cannot enforce those relationships.
Artifact paths use relative forward-slash paths without drive letters, parent/dot
segments, backslashes, or control characters. They are relative to the explicit
--evidence-root, not a hard-coded workspace. Without that option validation checks
structure and internal relationships only; it does not prove raw evidence exists.
With it, the validator checks the capture hash/version, resolves every observation
pointer, compares raw values, and rejects paths whose symlinks escape the root.
Offline analysis command
The first converter/analyser slice is available as:
python tools/analyse.py capture.json \
--evidence-root . \
--output diagnostic.json \
--reference-time 2026-09-15T12:00:00Z \
--producer-version VERSION
Input must be inside the explicit evidence root so output retains a portable
source path. Existing output requires --force. Exit codes are 0 for a validated
artifact, 1 for input, validation, or I/O failure, and 2 for invalid invocation.
The current catalog contains all 53 reviewed event classifications and seven
advisory watchlist entries. Actionable reliability-history records supplement
bounded event logs and are deduplicated by provider, event ID, normalized message,
and timestamp second. Other events remain traceable unanalysed findings. See
rules.md.
Mapping legacy captures
| Legacy input | Version-1 artifact mapping |
|---|---|
Capture schema_version 1 or 2 |
Preserve under metadata.source.schema_version; artifact version remains 1. Other capture versions are unsupported. |
generated_at, host/tool context |
Collection/reference timestamps and typed system/provenance facts. Do not invent historical producer revisions. |
sections.*.status/count/data/error |
Section state/count/reason and observations referencing original records. Retain native command outputs and nested failures. |
| Unrecognized section status | unavailable with a reason recording the original state; preserve original evidence. |
limit, truncated, diagnostic_collection |
Coverage evidence; absence of an old field must not imply truncation or successful collection. |
Compact summary |
Observations can point into /summary/...; declare the associated section/scope. Summary zero counts do not override explicit unavailable states. |
| Schema-1 recent_errors vs schema-2 recent_events | Normalize observed event facts without duplicating the old/new representations; retain pointers to chosen source records. |
/Date(milliseconds)/ and ISO timestamps |
Preserve raw values in observations; convert valid instants to timezone-qualified timestamps where used as normalized time. Unparseable required timestamps must produce an error, not today's date. |
| Unknown events | Preserve as observations and, when surfaced as findings, unanalysed; do not silently classify as healthy. |
| Human prose, executive summaries, remediation | Excluded from the engine contract; handled by the report adapter and human review. |
The legacy normalizer's health headline/score, display strings, inventory excerpts, and report remediation are not mandatory diagnostic fields. Existing snapshots remain migration comparisons, not new-schema examples.
Compatibility
Consumers select by explicit artifact version and reject unsupported versions. Breaking field or semantic changes require a new version and documented migration. Do not relabel raw captures or silently reshape historical artifacts. Contract v1 is the initial implementation. Event/watchlist analysis is migrated; native collection and broader non-event health analysis remain pending.
Schema and format behavior follow JSON Schema Draft 2020-12 and the jsonschema validator documentation. The validator enables format checking explicitly, including timezone-qualified dates.