feat(logging): tracing diagnostics with --log-format/--log-level (#51)

Cargo.toml

@@ -22,10 +22,13 @@ thiserror = "2"
 chrono = { version = "0.4", features = ["serde"] }
 sha2 = "0.10"
 rusqlite = { version = "0.32", features = ["bundled", "hooks"] }
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "json"] }
 
 [build-dependencies]
 chrono = "0.4"
 
 [dev-dependencies]
 tempfile = "3"
 proptest = "1"
+serde_json = "1"

docs/logging.adoc

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= VeriSimiser diagnostic logging
+:revdate: 2026-05-17
+
+VeriSimiser separates two output streams:
+
+stdout (data)::
+The answer to the command: JSON reports (`status --json`, `gc --json`,
+`validate --json`, `doctor --json`, `version --json`), the human-readable
+`status` / `gc` / `validate` report bodies, the `octad` table, and the
+`version` string. This contract is stable and machine-parseable; logging
+configuration never alters it.
+
+stderr (diagnostics)::
+Progress and status messages emitted via `tracing` (e.g. "parsing
+schema", "generated sidecar schema", "checking temporal drift",
+"created manifest"). Safe to discard; never parse stdout-bound data
+out of this stream.
+
+== Flags
+
+`--log-format=pretty|json`:: diagnostic rendering. Default `pretty`
+(human-readable, coloured). `json` emits one JSON object per line.
+`--log-level=trace|debug|info|warn|error`:: minimum level. Precedence:
+`--log-level` > `RUST_LOG` > `info`. `RUST_LOG` accepts the full
+`tracing-subscriber` `EnvFilter` syntax (e.g. `RUST_LOG=verisimiser=debug`).
+
+Both flags are global: they may appear before or after the subcommand.
+
+== JSON log schema
+
+With `--log-format=json`, each diagnostic line is a JSON object produced by
+`tracing-subscriber`'s JSON formatter. A machine-readable JSON Schema is at
+`docs/logging.schema.json`. Shape:
+
+[source,json]
+----
+{
+  "timestamp": "2026-05-17T12:34:56.789012Z",
+  "level": "INFO",
+  "target": "verisimiser",
+  "fields": { "message": "generated sidecar schema",
+              "path": ".verisim/sidecar_schema.sql" },
+  "spans": []
+}
+----
+
+`timestamp` (RFC 3339), `level` (`TRACE|DEBUG|INFO|WARN|ERROR`), `target`
+(emitting module), and `fields` (always contains `message`; structured
+key/values such as `path`, `schema`, `threshold`, `tables` are added per
+event) are always present. `spans` is present when emitted inside a span.
+Stable contract: consumers may rely on `timestamp`, `level`, `target`, and
+`fields.message`.

docs/logging.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hyperpolymath/verisimiser/docs/logging.schema.json",
+  "title": "VeriSimiser JSON diagnostic log line",
+  "description": "One line of `--log-format=json` output (stderr). stdout data output is NOT covered by this schema.",
+  "type": "object",
+  "required": ["timestamp", "level", "target", "fields"],
+  "properties": {
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "RFC 3339 / ISO 8601 event time."
+    },
+    "level": {
+      "type": "string",
+      "enum": ["TRACE", "DEBUG", "INFO", "WARN", "ERROR"]
+    },
+    "target": {
+      "type": "string",
+      "description": "Emitting module path, e.g. \"verisimiser\"."
+    },
+    "fields": {
+      "type": "object",
+      "required": ["message"],
+      "properties": {
+        "message": { "type": "string" }
+      },
+      "additionalProperties": true,
+      "description": "Always carries `message`; structured key/values (path, schema, threshold, tables, …) are added per event."
+    },
+    "spans": {
+      "type": "array",
+      "items": { "type": "object" }
+    }
+  },
+  "additionalProperties": true
+}