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
  governance/
    license.json                # when signed
    attestation.json            # when signed
    ledger/                     # lifecycle receipts (append-only)
      <event>.transition_request_v1.json
      <event>.signoff_v1.json
      <event>.waiver_v1.json
    checks/                     # check reports bound into transition requests by sha256
      <digest>.checks_v1.json
    decision_log/               # rationale blobs referenced by transition requests
      decision_log_<sha256>.txt
  support_bundle.zip              # optional

Lifecycle approvals (governance ledger)

Bundles can carry an event-sourced lifecycle. State is computed by replaying signed receipts under governance/ledger/.

Common commands:

helix governance status --bundle out/bundle
helix governance request-transition --bundle out/bundle --to Review --rationale @rationale.txt
helix governance signoff --bundle out/bundle --transition sha256:... --role scientific_owner --identity "alice" --signing-key keys/alice.ed25519
helix governance signoff --bundle out/bundle --transition sha256:... --role safety_reviewer --identity "bob" --signing-key keys/bob.ed25519
helix artifacts zip out/bundle

Official export gates:

• HELIX_GOVERNANCE_MODE=off|warn|enforce controls whether “official exports” (e.g., zipping a bundle, building a proof kit from a bundle) require Approved state or a waiver.
• SLACK_WEBHOOK_URL (optional) enables best-effort notifications on transition requests, signoffs, and when Approved becomes effective.

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.