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

Sellable artifact bundle (contract)

Helix turns CRISPR and Prime design into deterministic, shareable evidence bundles.

This page defines the one canonical artifact Helix produces for evaluation, support, and archival: the Helix artifact bundle.

What the bundle is

A Helix artifact bundle is a directory (or zip) with:

  • A machine-readable manifest (manifest.json) with per-file SHA-256.
  • The inputs used to generate outputs (at minimum: the run config JSON).
  • The session (.helix.json) containing the runs.
  • Human-friendly HTML report(s).
  • Portable exports (JSON + PNG) and an evidence JSON per run.

The CLI builds this bundle with:

helix artifacts build --config config.json --outdir out/bundle

Or, for first-run evaluation:

helix demo run

Bundle layout (v1)

<bundle_dir>/
  manifest.json
  inputs/
    config.json
  session/
    session.helix.json
  exports/
    <run_id>.export.json
    <run_id>.export.png
  reports/
    helix_report_<guide_id>_<run_id>.html
  evidence/
    <run_id>.evidence.json
  support_bundle.zip              # optional

Manifest schema

manifest.json is stable, deterministic, and content-addressed.

Key fields:

  • artifact_spec: semantic version for the bundle contract (currently 1.0.0)
  • schema: { kind, version } for machine parsing (helix.artifact_bundle, 1)
  • bundle_sha256: deterministic digest over {path, sha256} for every entry
  • entries[]: file list with {path, sha256, size, kind, role?}
  • helix_version, schema_version, git_sha: provenance and compatibility anchors

Inspect the manifest via:

helix artifacts manifest out/bundle

Guarantees

When Helix produces a bundle, it guarantees:

  • Deterministic structure: file paths are stable across runs of the same command.
  • Content integrity: every file is recorded with a SHA-256 in manifest.json.
  • Provenance: Helix version, schema registry version, and git SHA are recorded.
  • Offline by default: bundle generation does not require network access.

Versioning and compatibility policy

  • artifact_spec follows semver:
    • Patch: additive fields / new file kinds (backward compatible)
    • Minor: backward compatible structural extension
    • Major: breaking layout/schema changes (requires explicit migration tooling)
  • schema.version only increments on breaking manifest schema changes.