What a design campaign has to record

In development · specification stage

I am writing the specification for a platform that proposes antibody and nanobody variable domains against a declared antigen. Most of the document is about records. The failures I have watched in computational design came from lost provenance. Very few came from a weak architecture.

The output is a nomination

A generative run produces sequences, predicted structures and a set of scores used to rank them. Those are computational quantities. Affinity, stability, expression, immunogenicity and clinical safety are measurements. No run substitutes for them.

Writing that into a methods section does nothing by itself. Predictions and experimental decisions have to live in separate records, and no automated step may convert one into the other. The report templates enforce this. A candidate record has fields for predicted quantities and no field for a binding claim.

Campaign identity

A campaign is one design question together with the work performed to answer it. Its identity covers the items that change the meaning of the answer when they change:

• the antigen, to the level of structure revision, biological assembly, selected chains and residue map, with modifications, glycans and unresolved states listed;
• the intended epitope or contact region, and residues that must or must not be contacted;
• the molecular format, with fixed framework, linker, tag and constant-region context;
• the sequence and structure edits the run may make;
• the data, model, software, hardware and policy snapshots used to generate and to judge candidates;
• the experimental question a nominated candidate is meant to test.

Change any of them and you have started a new lineage. The rule addresses a specific failure: results generated against one antigen conformer get discussed later as though they applied to another, or a checkpoint gets swapped mid-programme and the earlier numbers stay in the deck. Both look like progress at the time and neither survives an audit.

Objects that need separate records

Three artefacts have to agree before a run is admissible. The state schema fixes tensor shapes, masks, units, coordinate frame and decoder identity. The run card supplies whatever varies between runs. The manifest lists inputs and outputs by cryptographic digest. Without its schema and data lock, a checkpoint is not usable as a model bundle. Loading one silently is how a programme loses six months of comparability.

Keeping the rejects

The evidence package holds the admitted candidates and the rejected comparators needed to audit selection. Storing the rejects costs disk and draws the most pushback. It is also the only way to answer the first question a reviewer asks: what did the filter remove, and would a different threshold have kept something better? A shortlist without its pool supports no claim about selection.

Storage planning follows from that decision, not from the candidate count. Budget for the full sampled pool at reduced precision plus the admitted set at full fidelity, and set per-campaign size caps in advance so the retention policy is a number in the run card, settled before anyone has a stake in the answer.

What a run card holds

The run card holds the choices that vary between runs. Anything absent from it is either fixed by the schema or a defect. A skeleton, with the identity-bearing fields first:

{
  "campaign_id": "vhh-vp3-2026-08",
  "lineage_parent": null,
  "antigen": {
    "sequence_sha256": "…",
    "structure_id": "…", "revision": "…", "assembly": 1,
    "chains": ["A", "B"], "residue_map_sha256": "…",
    "glycans": [], "unresolved": ["A:141-148"]
  },
  "design_schema": {
    "format": "VHH", "numbering": "IMGT",
    "editable_regions": ["CDR1", "CDR2", "CDR3"],
    "fixed_context": {"framework": "…", "linker": null, "tag": "His6"}
  },
  "model_bundle": {
    "weights_sha256": "…", "config_sha256": "…",
    "training_data_lock": "…"
  },
  "sampling": {
    "solver": "…", "steps": 200, "seeds": [11, 12, 13],
    "guidance": {"scale": 1.5}, "compute_ceiling_gpu_hours": 40
  },
  "admission": {
    "gates": ["G0", "G1", "G2", "G3", "G4"],
    "retain_rejected": true, "retention_gb": 250
  }
}

Admission compares three digests before the run starts. Failing early costs a minute; failing late invalidates the candidate set:

def admissible(schema, run_card, manifest):
    """A run is admissible only when the three records agree."""
    checks = [
        schema.digest == run_card.schema_digest,
        run_card.model_bundle.weights_sha256 in manifest.inputs,
        run_card.antigen.sequence_sha256 in manifest.inputs,
        run_card.model_bundle.training_data_lock is not None,
    ]
    return all(checks), [i for i, ok in enumerate(checks) if not ok]

Gate order

Development proceeds through ordered gates, each with checks written before the run and an outcome that counts as failure:

• governance, schemas and release boundary;
• runtime and hardware qualification;
• data and reference admission;
• molecular and antigen contracts;
• decoder and generative field;
• sampling, judging and selection;
• experimental validation and campaign release;
• clean replay from the archive.

Ordering them this way front-loads the cheap gates. A numbering-scheme mismatch or an unresolved-residue policy caught at gate four costs an afternoon; the same defect found after a sampling campaign invalidates the candidate set. Clean replay comes last because it tests the records, not the science. Rebuild the environment from the archive, re-run one campaign, and compare digests against the original manifest.

A failed gate is itself a result. It tells you which claim the programme was about to make without support, and learning that before an ordering decision is much cheaper than learning it after.

Status

This is a planned specification with preregistered checks, and no wet-lab campaign has run against it. The accurate description of the system today is a documented procedure for producing testable proposals. Published work on the generative side is covered in a separate note.

Stack

Generative side

Flow-matching and diffusion decoders over sequence and structure, with a predictive representation layer for conditioning

Structure and judging

Co-folding predictors for complexes, classical molecular dynamics for stability, and a multi-seed pose reranker

Molecular contracts

IMGT canonical numbering, region masks, scaffold profiles, cysteine ledger, VH/VL pairing rules

Developability

Chemical-liability motifs, predicted MHC-II presentation load, glycan-occlusion scenarios

Reproducibility

Content-addressed manifests, pinned container images, signed campaign specifications, offline replay from archive

Compute

Two-cluster split: training and generation on one profile, assembly and inference benchmarking on the other

References

1. Lipman Y. et al. Flow matching for generative modeling. doi:10.48550/arXiv.2210.02747
2. Assran M. et al. Self-supervised learning from images with a joint-embedding predictive architecture. doi:10.48550/arXiv.2301.08243
3. Abramson J. et al. Accurate structure prediction of biomolecular interactions with AlphaFold 3. doi:10.1038/s41586-024-07487-w
4. Lefranc M.-P. et al. IMGT unique numbering for immunoglobulin and T cell receptor variable domains. doi:10.1016/S0145-305X(02)00039-3
5. Dunbar J., Deane C. M. ANARCI: antigen receptor numbering and receptor classification. doi:10.1093/bioinformatics/btv552
6. Wilkinson M. D. et al. The FAIR Guiding Principles for scientific data management and stewardship. doi:10.1038/sdata.2016.18