# Diagnostic contract version 1 The implemented public interface is [diagnostic.schema.json](../schemas/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: ```bash 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: ```bash bash tools/analyse.sh 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](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](https://json-schema.org/draft/2020-12/json-schema-validation) and the [jsonschema validator documentation](https://python-jsonschema.readthedocs.io/en/stable/validate/). The validator enables format checking explicitly, including timezone-qualified dates.