Off-target constraint semantics (Summary Contract v2)

Helix treats off-target detection as a first-class constraint in Summary Contract v2:

• risk.off_target is always emitted (never omitted).
• Policy drives the requested mode, but the contract always records the executed mode.
• The validator enforces grade caps and honesty invariants so audits don’t depend on prose parsing.

Fields and meanings

Mode selection and downgrade detection

risk.off_target contains three mode-related fields:

• off_target_mode: where the mode came from (policy or an explicit override like screening).
• mode: the resolved target mode (none|screening|full).
• executed_mode: the algorithm actually executed (none|screening|full).

Contracts must treat mode != executed_mode as a structural downgrade. For example:

• mode=full, executed_mode=screening means “full requested/resolved, but only screening ran”.

Status

• status: computed|not_computed
• When status=not_computed, severity and reason are required.

Scope and limitations

• scope is a structured summary of search coverage:
  • none (no off-target computation)
  • window_only (screening within a provided genome window)
  • genome_wide (full search)
• limitations is always present and must describe bounds honestly.

Annotation honesty

Off-target feature overlap annotation (coding/promoter/enhancer/splice) must be explicitly honest:

• annotation_computed=false means annotation tracks were not available.
• When annotation_computed=false, limitations must include the standardized tag annotation_not_computed.
• When annotation_computed=false, per-site top_sites[].annotation must either be empty or have status=not_computed (no “half-computed” structures).

Grade caps (validator-enforced)

The validator enforces grade caps using structural conditions (not prose):

• If risk.off_target.status=not_computed and severity=blocking, then verdict.grade cannot be A or B.
• If risk.off_target.mode=full but executed_mode!=full, then verdict.grade cannot be A or B.

This prevents “silent downgrade” failures where runs appear compliant while skipping required computation.

Determinism and caching

Computed results may include:

• cache_key: sha256:* over all knobs that change results, including:
  • reference_id
  • provider identity and version
  • guide identity/sequence and PAM semantics
  • resolved mode / executed_mode
  • canonicalized params (mismatch bounds, hit caps, seed/scoring knobs)
  • window digest (contig names, sequence lengths, sha256) and window start bp

For fixed inputs, risk.off_target must be deterministic:

• stable candidate ordering and tie breaks (e.g. locus string ordering)
• stable JSON serialization for top_sites

Screening guarantees (minimum contract)

Screening is a cheap, conservative signal:

• Only searches a bounded window (scope=window_only).
• Applies mismatch/hit caps from policy/params.
• Produces deterministic top_sites and aggregate burden metrics (worst_site_score, sum_score).
• Does not claim calibrated cleavage probabilities unless explicitly calibrated and documented.

Implementation references

• Builder + validator: src/helix/studio/summary_contract_v2.py
• Summary strip surfacing: src/helix/studio/outcome_explorer.py