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

Governance & Licensing (Public Contract)

This page is the public contract for how Helix treats authority, signatures, and verification. It exists to prevent “sales/support drift” and to keep trust properties stable over time.

Definitions

  • Exploratory: you can simulate and explore locally, but outputs are not “decision-grade”.
  • Decision-grade: Helix is asserting governance-level guarantees under an explicit license and policy.
  • Signed bundle: an artifact bundle that includes license lineage plus an attestation signature.
  • Verification: offline checks that a bundle’s hashes, license lineage, and signatures are valid.

The rules (non-negotiable)

  1. Exploratory runs are always allowed.
  2. Decision-grade requires a Governance license.
  3. Signed bundles include license lineage plus an attestation.
  4. Verification is always free and offline.
  5. Verification fails closed for decision-grade claims.
    • Unsigned bundles cannot verify as decision-grade.
    • Bundles with invalid manifests/attestations cannot verify.

What is (and isn’t) paywalled

  • Free users may compute: simulate, explore, export exploratory artifacts.
  • Licensed users may assert: decision-grade outputs and signed bundles.

Migration (distribution rename)

If you previously installed the legacy PyPI distribution helix-governance, migrate with:

python -m pip uninstall -y helix-governance
python -m pip install -U helix-governance

This is a packaging rename only:

  • Module namespace stays helix
  • CLI entrypoint stays helix
  • Studio entrypoint stays helix-studio

Bundle signing + verification (CLI)

Configure license (offline)

  • HELIX_LICENSE_PATH=/path/to/license.json
  • HELIX_EDIT_PROGRAM_ID=<edit_program_id>

Build a signed bundle

helix artifacts build \
  --config cfg.json \
  --outdir out/bundle \
  --sign \
  --signing-key /path/to/signer.ed25519

The signed bundle includes:

  • governance/license.json (license lineage)
  • governance/attestation.json (signature over the bundle identity)

Verify (always free + offline)

helix verify out/bundle
helix verify out/bundle.zip

Verification never reads your local license file; it only validates what is inside the bundle.

Trust chain (diagram)

Helix (issuer)  ──signs──▶  License (helix-license.v1)         [pinned issuer keys in the build]
                                 │
                                 ▼
Decision-grade run summary includes provenance.license:
  license_id, license_sha256, issuer_key_id, org, edit_program_id
                                 │
                                 ▼
Signed bundle:
  manifest.json (hashes) + governance/attestation.json (signature over bundle identity)
                                 │
                                 ▼
Verifier (free, offline):
  checks manifest hashes + license signature + attestation signature  →  VERIFIED / FAILED

Provenance header format (exports + reports)

Every human-facing export surface includes:

  • A single-line provenance header (stable formatting).
  • A small JSON block with the same fields (machine readable).

Surfaces:

  • *.export.json (provenance_header, provenance_block)
  • *.evidence.json (provenance_header, provenance_block)
  • HTML report (rendered as a “Provenance” panel)

Header line is always in a fixed field order (placeholders do not reorder fields):

Helix provenance: mode=<MODE> policy=<POLICY> license=<LICENSE> issuer=<ISSUER> attestation=<ATTESTATION>

Policy label selection:

  • Prefer policy_id when present.
  • Else fall back to policy_profile when present.
  • Else fall back to short policy_hash (sha256:<first10>).

Missing values render as none (or unknown for policy when no policy fields exist).

CLI session contract (v2)

The user-facing Helix CLI session lifecycle is treated as a versioned external contract (bytes on disk), not an internal implementation detail.

See: Helix CLI Session Contract v2.

CI usage patterns (copy/paste)

Typical decision-grade CI flow:

python -m pip install -U helix-governance

export HELIX_LICENSE_PATH=/path/to/license.json
export HELIX_EDIT_PROGRAM_ID=<edit_program_id>
export HELIX_POLICY_PATH=/path/to/policy.json   # optional

# Optional: audit pinned issuer key ids (offline).
helix license issuer-keys --json > helix_issuer_keys.json

# Offline readiness snapshot (no secrets).
helix governance self-check \
  --json \
  --strict \
  --decision-mode decision_grade \
  --signing-key /path/to/signer.ed25519 \
  > helix_governance_self_check.json

# Build a signed bundle (license-gated) and verify it (always free + offline).
helix artifacts build \
  --config cfg.json \
  --outdir out/bundle \
  --sign \
  --signing-key /path/to/signer.ed25519

helix verify out/bundle --json-out helix_verify_bundle.json

If you need a single artifact for support tickets / CI logs, also capture:

helix support bundle --out helix_support_bundle.zip

Studio launch (optional)

Helix Studio uses the same env vars:

export HELIX_LICENSE_PATH=/path/to/license.json
export HELIX_EDIT_PROGRAM_ID=<edit_program_id>

helix-studio

Canonical error codes

All governance hard-stops surface one of these codes:

  • LICENSE_REQUIRED
  • LICENSE_INVALID
  • LICENSE_EXPIRED
  • LICENSE_NOT_YET_VALID
  • LICENSE_SCOPE_MISMATCH
  • SIGNING_KEY_REQUIRED
  • POLICY_LOCK_VIOLATION
  • ATTESTATION_INVALID
  • MANIFEST_MISMATCH