135 lines
8.1 KiB
Markdown
135 lines
8.1 KiB
Markdown
# 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 Typst 0.15 or newer are required at runtime. From a standalone component checkout:
|
||
|
||
```bash
|
||
bash tools/validate.sh examples/diagnostic.json
|
||
bash tools/validate.sh examples/diagnostic.json --evidence-root tests/fixtures/legacy
|
||
./tests/test.sh
|
||
```
|
||
|
||
The test target creates a uv-managed Python environment and synchronizes the
|
||
pinned test dependencies from `tests/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
|
||
./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.
|