Helix StudioGenome IDE
← Docs
Helix CLI docs
Browse Helix CLI docs

Export Governance & Provenance

Helix treats exported artifacts (HTML/CSV/PNG/etc.) as portable evidence that must remain:

  • human-readable (screenshot-safe labels),
  • machine-readable (embedded/sidecar JSON),
  • tamper-evident (hashes over canonical payloads and, where possible, file bytes).

This doc defines what Helix guarantees today and how to verify it offline.

What “NOT DECISION-GRADE” means

When an export is generated in demo or exploratory mode, Helix labels it:

DEMO — NOT DECISION-GRADE or EXPLORATORY — NOT DECISION-GRADE

This label is intended to survive screenshots and slide decks. It means the run does not satisfy decision-grade readiness gates (calibration/evidence completeness/etc.).

Export provenance contract

Helix emits a machine-readable provenance payload with schema:

helix_export_provenance_v1

This payload is used in:

  • HTML exports: embedded inside the HTML (<script id="helix-export-provenance" type="application/json">…</script>)
  • CSV exports: written as a sidecar file (<file>.provenance.json)

Canonicalization (c14n) and hash

When Helix computes a provenance hash, it uses a canonical JSON representation:

  • UTF-8 encoding
  • sorted keys
  • no insignificant whitespace (separators=(",", ":"))

The hash is:

sha256(c14n_json_bytes(payload))

HTML exports

HTML session reports embed:

  • the provenance JSON payload (helix-export-provenance)
  • a meta tag with the canonical hash:
    • <meta name="helix:export_provenance_sha256" content="sha256:<hex>">
  • the same hash echoed in the visible Governance panel for screenshot/audit convenience

CSV exports

CSV exports write a *.provenance.json sidecar that includes:

  • the provenance payload (helix_export_provenance_v1)
  • export.sha256 (sha256 over the raw exported CSV bytes) so that a verifier can detect accidental edits

PNG exports

PNG exports embed best-effort metadata in PNG text chunks:

  • helix_governance (JSON)
  • helix_limitations (JSON)

Note: some image manipulation tools may strip PNG metadata. The visible watermark remains the primary human-facing guardrail.

Verification (offline)

Helix ships a verifier that checks embedded/sidecar provenance and hashes:

helix verify-export <path>
# or
helix verify export <path>

Supported inputs:

  • HTML session reports (.html)
  • CSV files with sidecars (.csv + .provenance.json)
  • provenance sidecars (*.provenance.json)
  • PNG exports with helix_governance metadata (.png)
  • evidence exports (helix_run_evidence_v1.json)

The verifier exits nonzero on mismatch and prints a concise summary:

  • label
  • mode_class
  • decision_grade
  • is_demo
  • run_id
  • provenance_sha256 (when available)
  • export_sha256

What is and isn’t guaranteed (threat model)

Guaranteed:

  • Exports include a stable, screenshot-safe label for demo/exploratory runs.
  • HTML provenance hashes detect edits to the embedded provenance payload when the meta tag remains present.
  • CSV sidecars can detect accidental CSV edits via export.sha256.

Not guaranteed:

  • This is tamper-evident, not tamper-proof. A malicious actor can remove provenance blocks entirely.
  • PNG metadata is best-effort and may be stripped by third-party tools.

If you need stronger guarantees, the next step is signing exported provenance (or signing bundles of exports) using the same cryptographic trust chain used for validation verdicts.