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

Helix Governance + Registry Policy (Org V1)

Helix is a pre-clinical, in-silico simulation and exploration platform. This document defines the minimum internal policy needed to make Helix a system of record that teams cannot quietly bypass.

If it’s not in Helix, it did not happen.

Scope

This policy applies to:

  • any “official” exported artifact (proof kits, evidence packs, deterministic bundle zips, reports)
  • any program version intended for reuse across teams

This policy does not replace the product boundary rules in docs/positioning.md.

Definitions (V1)

  • Bundle: a canonical, deterministic artifact directory/zip that includes inputs, outputs, receipts, and summary.
  • Receipt: a signed, immutable governance event recorded in the bundle ledger.
  • Lifecycle State: computed by replaying governance receipts (Draft → Review → Approved → Deprecated).
  • Registry Ref: governance/registry_ref.json binding a bundle to programId@version + approvedReceiptId.
  • ProgramVersion: a published, semver’d, Approved bundle addressable by programId@version.
  • needsReview: registry impact state that blocks official exports until acknowledged or reapproved.

Policy: official outputs are governed and registered

In production posture:

  1. Official exports MUST come from a bundle that is:
    • integrity verified
    • governance state = Approved (valid approval chain)
    • registered (governance/registry_ref.json present and valid)
    • not blocked by registry status (deprecated/needsReview)
  2. Official exports MUST fail closed when:
    • the registry is unreachable, or
    • required blobs/inputs are missing, or
    • required receipts/checks are missing

Approvals (multi-party, receipt-based)

  • Approvals are event-sourced: state is computed from the bundle’s governance ledger (no mutable “state string”).
  • “Approved” requires:
    • required checks bound to the approval transition (checks report digest is signed by signers)
    • required roles/signoffs (at minimum: scientific_owner + safety_reviewer)
  • All signoffs MUST include signer identity, role, timestamp, and key id in the signed receipt.

Change control (reapproval or waiver)

  • Meaningful changes MUST force reapproval (new approval transition) OR a signed waiver.
  • Meaningful change is enforced by comparing approval_surface_hash between approvals.
  • Waivers MUST be signed, scoped, and include a short justification (and are always recorded in the ledger).

Registry (publish, reuse, and impact propagation)

  • Publishing a ProgramVersion MUST require governance Approved (or explicit publish waiver).
  • Dependencies SHOULD be declared explicitly between ProgramVersions.
  • Deprecating a base ProgramVersion MUST propagate impact:
    • dependents become needsReview
    • in enforce posture, dependents are blocked from official exports until acknowledged/reapproved/waived

CI expectations (GitHub)

  • The Helix Verify/Diff workflow is the required safety rail for repos that store bundles/receipts/registry refs.
  • Fork PRs MUST not brick CI if PR commenting is unavailable (summary still appears in artifacts/logs).

Branch protection requirement

  • master MUST require the Helix Verify/Diff check and prohibit direct pushes (PRs only).
  • Exceptions require an explicit waiver recorded in the decision log (and a linked GitHub issue).

Storage expectations (S3/MinIO)

  • Blob storage MUST be content-addressed and immutable (sha256 keys).
  • Streaming reads are required; missing blobs and auth errors fail closed.
  • Recommended posture:
    • HELIX_BLOB_BACKEND=s3
    • HELIX_S3_STRICT_NO_OVERWRITE=1

Set these in production deployment templates:

export HELIX_GOVERNANCE_MODE=enforce
export HELIX_REGISTRY_URL=...
export HELIX_REGISTRY_TOKEN=...
unset HELIX_REGISTRY_ALLOW_UNREGISTERED_EXPORT

export HELIX_BLOB_BACKEND=s3
export HELIX_S3_BUCKET=...
export HELIX_S3_PREFIX=prod
export HELIX_S3_STRICT_NO_OVERWRITE=1

Outages / emergency procedure

  • If registry/blob storage is down in enforce posture, official exports are blocked by default.
  • Emergency exception path: use a signed waiver with an explicit scope, then follow up by reapproving/acknowledging once services recover.