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

Run Graph v1 and Divergence Report v1

Run Graph (run-graph/v1)

  • What: Semantic execution graph emitted per HelixSpec run (run_graph.json, hashed in manifest and receipts).
  • Node IDs: sha256 of canonical JSON containing op, op_version, contract hash, policy hash, backend fingerprint hash, input semantic digests by port, and canonical params. File paths and timestamps are excluded.
  • Required node fields: node_id, op, op_version, kind, inputs, params, determinism, contract_clause (optional), artifacts_out, semantic_digest, value_digest, metrics (optional).
  • Required edge fields: src, dst, port, edge_kind (data|control|policy|environment).
  • Outputs map: points well-known semantic outputs (engine_edit_plan, engine_experiment_spec, results, receipts) to node_ids.
  • Graph hash: graph_hash is sha256 of canonical graph payload.
  • Binding: run_graph_path, run_graph_sha256, and run_graph_hash are recorded in receipts.

Divergence Report (divergence-report/v1)

  • Matching rule: Nodes match by node_id (semantic). Shared set = intersection of node_ids.
  • Frontier selection: Nodes present only in one graph whose parents are shared (or have no parents) form the frontier.
  • Minimal causal subgraph: For each frontier node, walk ancestors until shared nodes; include edges along those paths.
  • Cause types: environment_change (backend fingerprint hash diff), policy_change (policy hash/profile diff), semantic_contract_change (semantic hash diff), parameter_change (frontier with shared parents), input_change (frontier without shared parents). Each cause includes evidence hashes/fields:
    • param_change: param_json_pointer, before, after
    • input_change: artifact path + schema ids + sha256 before/after
    • environment_change: backend fingerprint hashes
    • policy_change: policy hash/profile before/after
  • Summary: summary_lines provide deterministic, human-readable statements; no timestamps or randomness.
  • Artifacts: CLI helix trust divergence --a bundleA --b bundleB --out report.json writes canonical JSON. Attach header is planned; current report is raw JSON with report_hash.

Trust toolchain (copy/paste):

helix trust fingerprint
helix trust explain --a path_to_bundleA --b path_to_bundleB
helix trust divergence --a path_to_bundleA --b path_to_bundleB --bundle proof_dir
helix verify proof_dir/manifest.json