Report provenance

A run’s report tables are only useful if a reader can tell which files they came from and whether they changed after they were written. write_report writes a report_provenance.json sidecar beside the tables. The sidecar is a manifest, not a signature: it records SHA-256 digests so a reader can detect a changed file, but it does not prove who produced it.

Schema

The sidecar uses ws4.report.provenance.v1. Its top-level fields are:

Field

Contents

schema_version

ws4.report.provenance.v1.

generated_utc

The UTC time the sidecar was written, as an ISO-8601 timestamp.

run

id, the run identifier supplied by the caller or the report directory’s name.

dataset

The dataset id, manifest_sha256, schema_version, and source list when a dataset is known. It is null when no dataset identifier is available.

reports

One entry per report table the writer produced: name, bytes, sha256, and status.

sources

One entry per source metadata file that exists: the same fields as reports, plus status and, for malformed JSON, an error.

uncertainty

status, source, and statement. See Uncertainty.

warnings

Text messages for missing report files or malformed source metadata. Missing metadata is normal and does not produce a warning by itself.

The writer hashes these report tables when it writes them:

  • report_accounts.csv

  • report_targets.csv

  • ending_inventory.csv

  • report_dhi.csv, when DHI accounts are present

  • report_structure_habitat.csv, when structure-habitat accounts are present

  • report_resilience.csv, when resilience accounts are present

It hashes these run-local source metadata files when they exist:

  • dhi_metadata.json

  • structure_habitat_metadata.json

  • resilience_metadata.json

Example

{
  "schema_version": "ws4.report.provenance.v1",
  "generated_utc": "2026-11-03T00:00:00+00:00",
  "run": {"id": "tsa24-base"},
  "dataset": {
    "id": "tsa24",
    "manifest_sha256": "2f6c...",
    "schema_version": "ws4.dataset.v1",
    "status": "ok"
  },
  "reports": [
    {
      "name": "report_accounts.csv",
      "bytes": 4812,
      "sha256": "24d1...",
      "status": "hashed"
    }
  ],
  "sources": [
    {
      "name": "dhi_metadata.json",
      "bytes": 912,
      "sha256": "ab90...",
      "status": "ok"
    }
  ],
  "uncertainty": {
    "status": "not_stated",
    "source": null,
    "statement": null
  },
  "warnings": []
}

Check a digest with the standard tool:

sha256sum report_accounts.csv

Uncertainty

The sidecar does not invent an uncertainty statement. Its status is not_stated unless a source metadata file carries one of these fields:

  • uncertainty as an object with a status (or level), and an optional statement or notes;

  • uncertainty as a non-empty string, recorded as stated;

  • uncertainty_status as a non-empty string.

When a source supplies one, uncertainty.source names that file. A report that has no uncertainty metadata therefore says not_stated rather than presenting silence as agreement.

Missing and invalid inputs

A missing source metadata file is simply absent from sources. A malformed file is still hashed and recorded with status invalid and an error; report writing continues. A missing report file named in the record is kept with null bytes and sha256 and status missing plus a warning. A missing dataset manifest leaves the dataset id in place with status missing.

Web service

GET /api/runs/{run}/reports keeps the existing name and bytes fields and adds sha256 where the sidecar recorded one. The report_provenance.json entry also carries the decoded sidecar under provenance. The Reports tab shows a provenance badge with the uncertainty status and links to the sidecar and any source metadata files. The browser renders those values as text nodes; it does not recompute a digest or a status.

Limits

  • A digest detects change; it is not a signature, a timestamp authority, or a trust anchor.

  • The sidecar records the report tables and the three run-local metadata files. It does not hash the whole dataset or the schedule.

  • The writer records the identifiers the caller supplies. A report run outside a managed run directory may have no dataset identity.

  • not_stated means exactly that. It is not a claim that the model is free of uncertainty.