Decision Support Spec v0 (Context v0 + Gate 0/1/2)

This document is the single source of truth for:

• Context v0 identity (supported_context_id, context_hash)
• Gate rules (0/1/2) and allowed/disallowed claims
• Baseline H0 pinning rules
• Calibration bundle approval + matching rules
• Export artifact enforcement rules (export_package, offline validation)

This spec is intentionally strict and “boring”: if something is not explicitly allowed, it is disallowed.

---

1) Terms

• Decision support: any UI/export behavior that could be interpreted as recommending an action.
• Gate level: an integer 0–2 that determines which output schema is legal.
• Context v0: an exact tuple of fields that defines what a model output means.
• Dataset version hash: a canonical hash over run inputs + pipeline identity.
• Calibration bundle: an approved mapping from (model_hash, context_hash, dataset_version_hash) -> gate_level.
• Baseline H0: a pinned baseline implementation used for uplift/benchmark comparisons.

---

2) Context v0

2.1 Context tuple (exact match)

Context v0 is an exact tuple match over these fields (no fuzzy matching):

• organism (e.g., human)
• genome_build (e.g., hg38)
• assay (e.g., ampseq)
• edit_type (e.g., crispr)
• measurement (e.g., indel_profile)

Any mismatch yields hard denial with a stable denial_reason_code.

2.2 Context hash (canonical)

context_hash is computed as:

• Canonical JSON bytes: helix.scientific_contract.canonical_json_bytes(obj)
• Hash: sha256(canonical_bytes)
• Stored as sha256:<hex>

The hashed payload is the context_tuple object.

---

3) Claims policy (A1/A2/A3)

3.1 Allowed claim families

• A1: comparative ranking/selection metrics (e.g., uplift vs baseline, NDCG@K) only if the relevant gate rules are satisfied.
• A2: binary labels (e.g., escape/non-escape) only if QC criteria and held-out split rules are satisfied.
• A3: provenance + integrity statements (hashes, signatures, schema validation, determinism class).

3.2 Disallowed claims (always)

Unless explicitly permitted by the gate level, Helix must not emit:

• Clinical outcome likelihoods
• Treatment guidance
• “Probability of success” language without Gate 2
• Uncalibrated probabilities or pseudo-probabilities in Gate 0/1
• Any UI copy that implies decision-grade support when decision support is disabled

---

4) Gate rules

Gate 0 (Exploratory)

Intent: ranking/triage only.

Hard constraints:

• Outputs cannot represent probabilities in any form.
• Any numeric outcome values are scores only.
• Export schema: schemas/outputs/gate0.schema.json

Gate 1 (Context-validated, still non-probabilistic)

Intent: structured analysis + comparability without probabilistic claims.

Hard constraints:

• Outputs still cannot represent probabilities.
• Requires dataset_version_hash record (see §5).
• May include baseline comparisons, but only if baseline is pinned (see §6).
• Export schema: schemas/outputs/gate1.schema.json

Gate 2 (Decision-grade probabilities)

Intent: calibrated probabilities and decision-grade semantics.

Hard constraints:

• Outputs must include calibrated probabilities and confidence intervals.
• Requires an approved calibration bundle entry matching:
  • model_hash, context_hash, dataset_version_hash
• Export schema: schemas/outputs/gate2.schema.json

---

5) Dataset version hashing (dataset_version_hash)

dataset_version_hash is a canonical hash over:

• fastq_files[]: {path, sha256, bytes}
• pipeline_digest: pinned pipeline/container digest (or equivalent immutable identity)

The export must include a complete computation record (see schemas/dataset_version.schema.json).

Any change to the FASTQ checksum list or pipeline digest must change dataset_version_hash.

---

6) Baseline H0 pinning

If any export includes baseline-derived metrics (uplift, baseline score, etc.), the export must include:

• baseline_manifest.json (copied from pinned baseline directory)
• baseline_id + baseline_hash in the run manifest

Any mismatch in baseline_hash invalidates uplift comparability (treat as a re-benchmark event).

Pinned baseline lives at baselines/h0/.

---

7) Enforcement and non-bypassability

7.1 One export entry point

All decision-support exports must route through a single function:

export_package(run_state, outputs, export_dir)

The function must always write (atomically, no partial exports):

• run_manifest.json
• outputs.json
• checksums.json
• baseline_manifest.json iff baseline metrics are present
• calibration_bundle_ref.json iff gate level ≥ 1
• any additional images/reports if provided by the caller

Then it must run:

• Schema validation (manifest + outputs)
• Hash/checksum computation verification

If any step fails, the export fails.

7.2 Non-bypassable offline validation (fail closed)

export_package MUST:

• Write all export bytes to a temporary export directory first.
• Run the offline validator on that exact byteset.
• Only then finalize the export (atomic rename into the destination).

If offline validation fails, export_package MUST fail closed and MUST NOT leave a partially-written export directory at the destination path.

Offline validation MUST NOT depend on network access. Any required reference material must be included in the export package and/or shipped as part of the Helix build.

Temporary export retention is forbidden unless explicitly enabled for debugging via HELIX_DECISION_SUPPORT_EXPORT_DEBUG=1.

7.3 Decision support is computed, not toggled

decision_support_enabled is derived from:

• Supported context exact match
• Gate constraints satisfied
• Calibration bundle approved when required
• ood_flag is false
• dataset_version_hash present when gate ≥ 1

The UI may request decision support; it cannot force it.

---

8) Artifacts and schemas

• Run manifest schema: schemas/run_manifest.schema.json
• Dataset version schema: schemas/dataset_version.schema.json
• Outputs schemas:
  • Gate0: schemas/outputs/gate0.schema.json
  • Gate1: schemas/outputs/gate1.schema.json
  • Gate2: schemas/outputs/gate2.schema.json

Offline validator: tools/validate_artifact.py

---

9) Acceptance map (spec v0)