@morscherlab/mint-sdk 1.0.0-beta.2 → 1.0.0-beta.4

package/src/templates/builders.ts

@@ -0,0 +1,2149 @@
+import type {
+  AssayFeature,
+  AssayMatrixTemplate,
+  AssayMatrixTemplateData,
+  AssaySample,
+  BioTemplateEnvelope,
+  CalibrationAcceptance,
+  CalibrationCurveTemplate,
+  CalibrationCurveTemplateData,
+  CalibrationPoint,
+  CalibrationPointInput,
+  CompoundDoseSeries,
+  ControlDefinition,
+  CreateBioTemplatePackCollectionOptions,
+  CreateElisaAssayCollectionOptions,
+  CreateLcmsBatchCollectionOptions,
+  CreateAssayMatrixTemplateOptions,
+  CreateCalibrationCurveTemplateOptions,
+  CreateDoseResponseTemplateOptions,
+  CreateFlowCytometryAssayCollectionOptions,
+  CreateWesternBlotAssayCollectionOptions,
+  CreateFlowCytometryPanelTemplateOptions,
+  CreateInstrumentRunTemplateOptions,
+  CreatePlateMapTemplateOptions,
+  CreateProtocolStepsTemplateOptions,
+  CreateQpcrExpressionCollectionOptions,
+  CreateQpcrPlateTemplateOptions,
+  CreateReagentListTemplateOptions,
+  CreateSampleSheetTemplateOptions,
+  CreateSamplePrepTemplateOptions,
+  CreateTimeCourseTemplateOptions,
+  CreateWellPlateScreenCollectionOptions,
+  DoseResponseTemplate,
+  DoseResponseTemplateData,
+  FlowCytometryPanelTemplate,
+  FlowCytometryPanelTemplateData,
+  FlowPanelControl,
+  FlowPanelMarker,
+  InstrumentMethod,
+  InstrumentRunItem,
+  InstrumentRunTemplate,
+  InstrumentRunTemplateData,
+  PlateMapTemplate,
+  PlateMapTemplateData,
+  ProtocolStepRecord,
+  ProtocolStepsTemplate,
+  ProtocolStepsTemplateData,
+  QpcrPlateTemplate,
+  QpcrPlateTemplateData,
+  QpcrReaction,
+  QpcrSample,
+  QpcrTarget,
+  ReagentListTemplate,
+  ReagentListTemplateData,
+  ReagentRecord,
+  ReagentTemplateInput,
+  TimeCourseCondition,
+  TimeCourseTemplate,
+  TimeCourseTemplateData,
+  TimePoint,
+  SampleRecord,
+  SampleSheetTemplate,
+  SampleSheetTemplateData,
+  SamplePrepStep,
+  SamplePrepStepInput,
+  SamplePrepTemplate,
+  SamplePrepTemplateData,
+  TemplateCollection,
+  TemplateCollectionEnvelope,
+  TemplateId,
+  TemplatePackId,
+  TemplatePresetId,
+  TemplateSample,
+} from './types'
+import type { WellPlateFormat } from '../types'
+import { getBioTemplateInfo } from './catalog'
+import { getBioTemplatePackInfo } from './packs'
+import { getBioTemplatePresetInfo } from './presets'
+
+export const TEMPLATE_COLLECTION_KEY = 'templates'
+
+const DEFAULT_SAMPLE_COLORS = [
+  '#3B82F6',
+  '#10B981',
+  '#EF4444',
+  '#F59E0B',
+  '#8B5CF6',
+  '#F97316',
+  '#06B6D4',
+  '#14B8A6',
+  '#6B7280',
+]
+
+const PLATE_DIMENSIONS: Record<number, readonly [number, number]> = {
+  6: [2, 3],
+  12: [3, 4],
+  24: [4, 6],
+  48: [6, 8],
+  54: [6, 9],
+  96: [8, 12],
+  384: [16, 24],
+}
+
+export function createTemplateEnvelope<TData>(
+  templateId: TemplateId,
+  data: TData,
+  metadata: Record<string, unknown> = {},
+  templateVersion = '1.0'
+): BioTemplateEnvelope<TData> {
+  return {
+    template_id: templateId,
+    template_version: templateVersion,
+    kind: 'experiment-design',
+    data,
+    metadata,
+  }
+}
+
+export function createPlateMapTemplate(
+  options: CreatePlateMapTemplateOptions = {}
+): PlateMapTemplate {
+  const {
+    id = 'plate-1',
+    name = 'Plate 1',
+    format = 96,
+    samples = [],
+    metadata = {},
+  } = options
+
+  const sampleDefinitions = samples.map((sample, index): TemplateSample => {
+    if (typeof sample !== 'string') return sample
+    return {
+      id: sampleIdFromName(sample, index),
+      name: sample,
+      color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+    }
+  })
+
+  return createTemplateEnvelope('plate-map', {
+    plates: [
+      {
+        id,
+        name,
+        format,
+        wells: {},
+      },
+    ],
+    samples: sampleDefinitions,
+    activePlateId: id,
+    selectedWells: [],
+  }, metadata)
+}
+
+export function createSampleSheetTemplate(
+  options: CreateSampleSheetTemplateOptions
+): SampleSheetTemplate {
+  const data: SampleSheetTemplateData = {
+    samples: options.samples.map(normalizeSampleRecord),
+    columns: options.columns ?? [
+      { id: 'sampleId', label: 'Sample ID', type: 'string', required: true, groupable: false },
+      { id: 'name', label: 'Name', type: 'string', required: false, groupable: false },
+    ],
+    groups: options.groups ?? [],
+  }
+  validateSampleSheetData(data)
+  return createTemplateEnvelope('sample-sheet', data, options.metadata ?? {})
+}
+
+export function createSamplePrepTemplate(
+  options: CreateSamplePrepTemplateOptions
+): SamplePrepTemplate {
+  const prepType = options.prepType ?? 'extraction'
+  const volumeUnit = options.volumeUnit ?? 'uL'
+  const steps: SamplePrepStep[] = []
+  let order = 1
+
+  for (const [index, sample] of options.samples.entries()) {
+    if (typeof sample !== 'string') {
+      const step = normalizeSamplePrepStep(sample, prepType, volumeUnit, order, index)
+      steps.push(step)
+      order = Math.max(order, step.order + 1)
+      continue
+    }
+    const sourceSampleId = idFromName(sample, `sample-${index + 1}`)
+    steps.push({
+      id: `${sourceSampleId}-prep`,
+      order,
+      type: prepType,
+      name: `Prepare ${sample}`,
+      sourceSampleId,
+      destinationSampleId: `${sourceSampleId}-prepared`,
+      inputVolume: options.inputVolume,
+      outputVolume: options.outputVolume,
+      volumeUnit,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  const data: SamplePrepTemplateData = {
+    protocolName: options.protocolName ?? 'Sample preparation',
+    steps,
+    metadata: options.metadata ?? {},
+  }
+  validateSamplePrepData(data)
+  return createTemplateEnvelope('sample-prep', data, options.metadata ?? {})
+}
+
+export function createDoseResponseTemplate(
+  options: CreateDoseResponseTemplateOptions
+): DoseResponseTemplate {
+  const compounds = Array.isArray(options.compounds)
+    ? options.compounds.map(normalizeCompound)
+    : Object.entries(options.compounds).map(([name, concentrations], index) => normalizeCompound({
+      id: compoundIdFromName(name, index),
+      name,
+      concentrations,
+      metadata: {},
+    }))
+
+  const layout = options.layout
+    ? isEnvelope<PlateMapTemplateData>(options.layout) ? options.layout.data : options.layout
+    : undefined
+
+  const data: DoseResponseTemplateData = {
+    compounds,
+    unit: options.unit,
+    replicates: options.replicates ?? 1,
+    controls: (options.controls ?? []).map(normalizeControl),
+    layout,
+    metadata: options.metadata ?? {},
+  }
+  validateDoseResponseData(data)
+  return createTemplateEnvelope('dose-response', data, options.metadata ?? {})
+}
+
+export function createCalibrationCurveTemplate(
+  options: CreateCalibrationCurveTemplateOptions
+): CalibrationCurveTemplate {
+  const unit = options.unit ?? 'uM'
+  const points: CalibrationPoint[] = []
+  let order = 1
+
+  if (options.includeBlank !== false) {
+    points.push({
+      id: 'blank',
+      order,
+      role: 'blank',
+      level: 'Blank',
+      concentration: 0,
+      unit,
+      replicate: 1,
+      include: true,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  const standardValues: number[] = []
+  for (const [index, concentration] of options.concentrations.entries()) {
+    if (typeof concentration !== 'number') {
+      const point = normalizeCalibrationPoint(concentration, unit, order, index)
+      points.push(point)
+      if (point.role === 'standard') standardValues.push(point.concentration)
+      order = Math.max(order, point.order + 1)
+      continue
+    }
+    standardValues.push(concentration)
+    points.push({
+      id: `std-${index + 1}`,
+      order,
+      role: 'standard',
+      level: `Standard ${index + 1}`,
+      concentration,
+      unit,
+      replicate: 1,
+      include: true,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  if (options.includeQc !== false) {
+    const positiveValues = [...standardValues].filter(value => value > 0).sort((a, b) => a - b)
+    const qcValues = positiveValues.length === 0
+      ? []
+      : positiveValues[0] === positiveValues[positiveValues.length - 1]
+        ? [positiveValues[0]]
+        : [positiveValues[0], positiveValues[positiveValues.length - 1]]
+    for (const [index, concentration] of qcValues.entries()) {
+      const level = index === 0 ? 'QC low' : 'QC high'
+      points.push({
+        id: idFromName(level, `qc-${index + 1}`),
+        order,
+        role: 'qc',
+        level,
+        concentration,
+        unit,
+        replicate: 1,
+        include: true,
+        status: 'planned',
+        metadata: {},
+      })
+      order += 1
+    }
+  }
+
+  const data: CalibrationCurveTemplateData = {
+    analyte: options.analyte ?? 'Analyte',
+    model: options.model ?? 'linear',
+    xUnit: unit,
+    responseUnit: options.responseUnit ?? 'response',
+    points,
+    acceptance: normalizeCalibrationAcceptance(options.acceptance, options.includeBlank !== false),
+    metadata: options.metadata ?? {},
+  }
+  validateCalibrationCurveData(data)
+  return createTemplateEnvelope('calibration-curve', data, options.metadata ?? {})
+}
+
+export function createTimeCourseTemplate(
+  options: CreateTimeCourseTemplateOptions
+): TimeCourseTemplate {
+  const timepoints = options.timepoints.map((timepoint, index): TimePoint => {
+    if (typeof timepoint !== 'number') return normalizeTimePoint(timepoint)
+    return {
+      id: timepointId(timepoint, options.unit, index),
+      label: `${timepoint} ${options.unit}`,
+      value: timepoint,
+      unit: options.unit,
+      metadata: {},
+    }
+  }).sort((a, b) => a.value - b.value)
+
+  const conditions = options.conditions.map((condition, index): TimeCourseCondition => {
+    if (typeof condition !== 'string') return normalizeCondition(condition)
+    return {
+      id: idFromName(condition, `condition-${index + 1}`),
+      name: condition,
+      color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+      metadata: {},
+    }
+  })
+
+  const samples = conditions.flatMap(condition =>
+    timepoints.flatMap(timepoint =>
+      Array.from({ length: options.replicates ?? 1 }, (_, index) => ({
+        sampleId: `${condition.id}-${timepoint.id}-r${index + 1}`,
+        conditionId: condition.id,
+        timepointId: timepoint.id,
+        replicate: index + 1,
+        metadata: {},
+      }))
+    )
+  )
+
+  const data: TimeCourseTemplateData = {
+    timepoints,
+    conditions,
+    samples,
+    metadata: options.metadata ?? {},
+  }
+  validateTimeCourseData(data)
+  return createTemplateEnvelope('time-course', data, options.metadata ?? {})
+}
+
+export function createProtocolStepsTemplate(
+  options: CreateProtocolStepsTemplateOptions
+): ProtocolStepsTemplate {
+  const steps = options.steps.map((step, index): ProtocolStepRecord => {
+    if (typeof step === 'string') {
+      return {
+        id: idFromName(step, `step-${index + 1}`),
+        type: 'custom',
+        name: step,
+        status: 'pending',
+        parameters: {},
+        order: index,
+        metadata: {},
+      }
+    }
+    return normalizeProtocolStep(step, index)
+  }).sort((a, b) => a.order - b.order)
+
+  const data: ProtocolStepsTemplateData = {
+    steps,
+    metadata: options.metadata ?? {},
+  }
+  validateProtocolStepsData(data)
+  return createTemplateEnvelope('protocol-steps', data, options.metadata ?? {})
+}
+
+export function createAssayMatrixTemplate(
+  options: CreateAssayMatrixTemplateOptions
+): AssayMatrixTemplate {
+  const samples = options.samples.map((sample, index): AssaySample => {
+    if (typeof sample !== 'string') return normalizeAssaySample(sample)
+    return {
+      sampleId: idFromName(sample, `sample-${index + 1}`),
+      name: sample,
+      metadata: {},
+    }
+  })
+  const features = options.features.map((feature, index): AssayFeature => {
+    if (typeof feature !== 'string') return normalizeAssayFeature(feature)
+    return {
+      id: idFromName(feature, `feature-${index + 1}`),
+      name: feature,
+      type: 'readout',
+      metadata: {},
+    }
+  })
+  const sampleLookup = createAssaySampleLookup(samples)
+  const featureLookup = createAssayFeatureLookup(features)
+  const measurements = Object.entries(options.values ?? {}).flatMap(([sampleId, featureValues]) =>
+    Object.entries(featureValues).map(([featureId, value]) => ({
+      sampleId: sampleLookup.get(sampleId) ?? sampleId,
+      featureId: featureLookup.get(featureId) ?? featureId,
+      value,
+      metadata: {},
+    }))
+  )
+
+  const data: AssayMatrixTemplateData = {
+    samples,
+    features,
+    measurements,
+    metadata: options.metadata ?? {},
+  }
+  validateAssayMatrixData(data)
+  return createTemplateEnvelope('assay-matrix', data, options.metadata ?? {})
+}
+
+export function createReagentListTemplate(
+  options: CreateReagentListTemplateOptions
+): ReagentListTemplate {
+  const reagents = options.reagents.map((reagent, index): ReagentRecord => {
+    if (typeof reagent !== 'string') return normalizeReagent(reagent)
+    return {
+      id: idFromName(reagent, `reagent-${index + 1}`),
+      name: reagent,
+      kind: 'reagent',
+      metadata: {},
+    }
+  })
+  const data: ReagentListTemplateData = {
+    reagents,
+    metadata: options.metadata ?? {},
+  }
+  validateReagentListData(data)
+  return createTemplateEnvelope('reagent-list', data, options.metadata ?? {})
+}
+
+export function createFlowCytometryPanelTemplate(
+  options: CreateFlowCytometryPanelTemplateOptions
+): FlowCytometryPanelTemplate {
+  const markers = options.markers.map((marker, index): FlowPanelMarker => {
+    if (typeof marker !== 'string') return normalizeFlowMarker(marker, index)
+    return {
+      id: idFromName(marker, `marker-${index + 1}`),
+      marker,
+      fluorophore: 'unassigned',
+      purpose: 'phenotype',
+      compensationRequired: true,
+      metadata: {},
+    }
+  })
+  const controls = options.controls === undefined
+    ? options.includeDefaultControls === false
+      ? []
+      : defaultFlowControls(markers)
+    : options.controls.map((control, index): FlowPanelControl => {
+        if (typeof control !== 'string') return normalizeFlowControl(control, index)
+        return {
+          id: idFromName(control, `control-${index + 1}`),
+          name: control,
+          kind: 'other',
+          required: true,
+          metadata: {},
+        }
+      })
+  const data: FlowCytometryPanelTemplateData = {
+    markers,
+    controls,
+    instrument: options.instrument,
+    metadata: options.metadata ?? {},
+  }
+  validateFlowCytometryPanelData(data)
+  return createTemplateEnvelope('flow-cytometry-panel', data, options.metadata ?? {})
+}
+
+export function createInstrumentRunTemplate(
+  options: CreateInstrumentRunTemplateOptions
+): InstrumentRunTemplate {
+  const method = typeof options.method === 'string' || options.method === undefined
+    ? {
+        id: idFromName(options.method ?? 'Default method', 'method-1'),
+        name: options.method ?? 'Default method',
+        instrument: options.instrument,
+        metadata: {},
+      }
+    : normalizeInstrumentMethod(options.method, options.instrument)
+  const items: InstrumentRunItem[] = []
+  let order = 1
+
+  if (options.includeBlanks !== false) {
+    items.push({
+      id: 'blank-start',
+      order,
+      kind: 'blank',
+      name: 'Blank start',
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  if (options.includeQc !== false) {
+    items.push({
+      id: 'qc-start',
+      order,
+      kind: 'qc',
+      name: 'QC start',
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  for (const [index, item] of options.items.entries()) {
+    if (typeof item !== 'string') {
+      const normalized = normalizeInstrumentRunItem(item, method.id, order, index)
+      items.push(normalized)
+      order = Math.max(order, normalized.order + 1)
+      continue
+    }
+    const sampleId = idFromName(item, `sample-${index + 1}`)
+    items.push({
+      id: `${sampleId}-run`,
+      order,
+      kind: 'sample',
+      sampleId,
+      name: item,
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+    order += 1
+  }
+
+  if (options.includeQc !== false) {
+    items.push({
+      id: 'qc-end',
+      order,
+      kind: 'qc',
+      name: 'QC end',
+      methodId: method.id,
+      status: 'planned',
+      metadata: {},
+    })
+  }
+
+  const data: InstrumentRunTemplateData = {
+    runId: 'run-1',
+    instrument: options.instrument,
+    methods: [method],
+    items,
+    metadata: options.metadata ?? {},
+  }
+  validateInstrumentRunData(data)
+  return createTemplateEnvelope('instrument-run', data, options.metadata ?? {})
+}
+
+export function createQpcrPlateTemplate(
+  options: CreateQpcrPlateTemplateOptions
+): QpcrPlateTemplate {
+  const format = options.format ?? 96
+  const replicates = options.replicates ?? 3
+  if (replicates < 1) {
+    throw new Error('qPCR replicates must be at least 1.')
+  }
+
+  const samples = options.samples.map((sample, index): QpcrSample => {
+    if (typeof sample !== 'string') return normalizeQpcrSample(sample)
+    return {
+      sampleId: idFromName(sample, `sample-${index + 1}`),
+      name: sample,
+      metadata: {},
+    }
+  })
+  const targets = options.targets.map((target, index): QpcrTarget => {
+    if (typeof target !== 'string') return normalizeQpcrTarget(target)
+    return {
+      id: idFromName(target, `target-${index + 1}`),
+      name: target,
+      metadata: {},
+    }
+  })
+  const wells = wellIdsForFormat(format)
+  let wellIndex = 0
+  const reactions: QpcrReaction[] = []
+
+  for (const sample of samples) {
+    for (const target of targets) {
+      for (let replicate = 1; replicate <= replicates; replicate += 1) {
+        const wellId = wells[wellIndex]
+        if (!wellId) throw new Error(`qPCR plate format ${format} does not have enough wells.`)
+        reactions.push({
+          id: `${sample.sampleId}-${target.id}-r${replicate}`,
+          wellId,
+          sampleId: sample.sampleId,
+          targetId: target.id,
+          replicate,
+          controlKind: 'sample',
+          flags: [],
+          metadata: {},
+        })
+        wellIndex += 1
+      }
+    }
+  }
+
+  if (options.includeNoTemplateControls !== false) {
+    for (const target of targets) {
+      const wellId = wells[wellIndex]
+      if (!wellId) throw new Error(`qPCR plate format ${format} does not have enough wells.`)
+      reactions.push({
+        id: `ntc-${target.id}`,
+        wellId,
+        targetId: target.id,
+        replicate: 1,
+        controlKind: 'no-template',
+        flags: [],
+        metadata: {},
+      })
+      wellIndex += 1
+    }
+  }
+
+  const data: QpcrPlateTemplateData = {
+    plateId: 'qpcr-plate-1',
+    format,
+    samples,
+    targets,
+    reactions,
+    instrument: options.instrument,
+    chemistry: options.chemistry ?? 'sybr',
+    metadata: options.metadata ?? {},
+  }
+  validateQpcrPlateData(data)
+  return createTemplateEnvelope('qpcr-plate', data, options.metadata ?? {})
+}
+
+export function createDefaultBioTemplate(templateId: TemplateId | string): BioTemplateEnvelope<unknown> {
+  const template = getBioTemplateInfo(templateId)
+  if (!template) {
+    throw new Error(`Unknown bio template '${templateId}'.`)
+  }
+
+  switch (template.template_id) {
+    case 'plate-map':
+      return createPlateMapTemplate({
+        name: 'Plate 1',
+        samples: ['Control', 'Treatment'],
+      })
+    case 'sample-sheet':
+      return createSampleSheetTemplate({
+        samples: [
+          { sampleId: 'S001', name: 'Control 1', group: 'Control' },
+          { sampleId: 'S002', name: 'Treatment 1', group: 'Treatment' },
+        ],
+      })
+    case 'sample-prep':
+      return createSamplePrepTemplate({
+        samples: ['S001', 'S002'],
+        prepType: 'extraction',
+        outputVolume: 50,
+      })
+    case 'dose-response':
+      return createDoseResponseTemplate({
+        compounds: {
+          'Compound A': [10, 1, 0.1],
+        },
+        unit: 'uM',
+        replicates: 3,
+      })
+    case 'calibration-curve':
+      return createCalibrationCurveTemplate({
+        concentrations: [0.1, 1, 10, 100],
+        analyte: 'Analyte',
+        unit: 'uM',
+      })
+    case 'time-course':
+      return createTimeCourseTemplate({
+        timepoints: [0, 6, 24],
+        unit: 'hour',
+        conditions: ['Control', 'Treatment'],
+        replicates: 3,
+      })
+    case 'protocol-steps':
+      return createProtocolStepsTemplate({
+        steps: [
+          {
+            id: 'seed-cells',
+            type: 'addition',
+            name: 'Seed cells',
+            description: 'Add cells to wells or culture vessels.',
+            duration: 15,
+          },
+          {
+            id: 'incubate-overnight',
+            type: 'incubation',
+            name: 'Incubate overnight',
+            duration: 960,
+            parameters: { temperature: '37 C', co2: '5%' },
+          },
+          {
+            id: 'measure-readout',
+            type: 'measurement',
+            name: 'Measure readout',
+            duration: 45,
+          },
+        ],
+      })
+    case 'assay-matrix':
+      return createAssayMatrixTemplate({
+        samples: ['S001', 'S002'],
+        features: ['Lactate', 'Glucose'],
+        values: {
+          s001: { lactate: 1.2, glucose: 5.4 },
+          s002: { lactate: 2.1, glucose: 4.8 },
+        },
+      })
+    case 'reagent-list':
+      return createReagentListTemplate({
+        reagents: ['DMSO', 'Compound A', 'Anti-HA antibody'],
+      })
+    case 'flow-cytometry-panel':
+      return createFlowCytometryPanelTemplate({
+        markers: ['CD3', 'CD4', 'CD8'],
+        instrument: 'BD LSRFortessa',
+      })
+    case 'instrument-run':
+      return createInstrumentRunTemplate({
+        items: ['S001', 'S002'],
+        instrument: 'LC-MS',
+        method: 'Default method',
+      })
+    case 'qpcr-plate':
+      return createQpcrPlateTemplate({
+        samples: ['Control', 'Treatment'],
+        targets: ['ACTB', 'GAPDH'],
+        replicates: 3,
+        instrument: 'QuantStudio',
+      })
+    default:
+      throw new Error(`Unknown bio template '${templateId}'.`)
+  }
+}
+
+export function createBioTemplatePackCollection(
+  name: TemplatePackId | string,
+  options: CreateBioTemplatePackCollectionOptions = {},
+): TemplateCollectionEnvelope {
+  const pack = getBioTemplatePackInfo(name)
+  if (!pack) {
+    throw new Error(`Unknown template pack '${name}'.`)
+  }
+
+  return createTemplateCollection(
+    pack.templates.map(templateId => createDefaultBioTemplate(templateId)),
+    { pack: pack.name, ...(options.metadata ?? {}) },
+  )
+}
+
+export function createWellPlateScreenCollection(
+  options: CreateWellPlateScreenCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const plate = createPlateMapTemplate({
+    name: options.plateName ?? 'Screen plate',
+    format: options.plateFormat ?? 96,
+    samples: sampleRecords.map((sample, index) => ({
+      id: sample.sampleId,
+      name: sample.name ?? sample.sampleId,
+      color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+    })),
+  })
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const doseResponse = createDoseResponseTemplate({
+    compounds: options.compounds ?? { 'Compound A': [10, 1, 0.1] },
+    unit: options.unit ?? 'uM',
+    replicates: options.replicates ?? 3,
+    layout: plate,
+  })
+  return createTemplateCollection(
+    [plate, sampleSheet, doseResponse],
+    { preset: 'wellplate-screen', ...(options.metadata ?? {}) }
+  )
+}
+
+export function createQpcrExpressionCollection(
+  options: CreateQpcrExpressionCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const qpcr = createQpcrPlateTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    targets: options.targets ?? ['ACTB', 'GAPDH'],
+    chemistry: options.chemistry,
+    format: options.format,
+    includeNoTemplateControls: options.includeNoTemplateControls,
+    replicates: options.replicates ?? 3,
+    instrument: options.instrument,
+  })
+  return createTemplateCollection(
+    [sampleSheet, qpcr],
+    { preset: 'qpcr-expression', ...(options.metadata ?? {}) }
+  )
+}
+
+export function createLcmsBatchCollection(
+  options: CreateLcmsBatchCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['S001', 'S002'])
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const instrumentRun = createInstrumentRunTemplate({
+    items: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name ?? sample.sampleId,
+    })),
+    method: options.method ?? 'Default method',
+    instrument: options.instrument ?? 'LC-MS',
+    includeQc: options.includeQc,
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: options.features ?? ['Glucose', 'Lactate'],
+  })
+  return createTemplateCollection(
+    [sampleSheet, instrumentRun, assayMatrix],
+    { preset: 'lcms-batch', ...(options.metadata ?? {}) }
+  )
+}
+
+export function createElisaAssayCollection(
+  options: CreateElisaAssayCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const analyte = options.analyte ?? 'Analyte'
+  const responseUnit = options.responseUnit ?? 'OD450'
+  const plate = createPlateMapTemplate({
+    name: options.plateName ?? 'ELISA plate',
+    format: options.plateFormat ?? 96,
+    samples: [
+      { id: 'blank', name: 'Blank' },
+      { id: 'standard', name: 'Standards' },
+      { id: 'qc', name: 'QC' },
+      ...sampleRecords.map((sample, index) => ({
+        id: sample.sampleId,
+        name: sample.name ?? sample.sampleId,
+        color: DEFAULT_SAMPLE_COLORS[index % DEFAULT_SAMPLE_COLORS.length],
+      })),
+    ],
+  })
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const calibrationCurve = createCalibrationCurveTemplate({
+    concentrations: options.standardConcentrations ?? [1000, 100, 10, 1],
+    analyte,
+    unit: options.unit ?? 'pg/mL',
+    responseUnit,
+    model: 'four-parameter-logistic',
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: [{
+      id: idFromName(analyte, 'analyte'),
+      name: analyte,
+      type: 'protein',
+      unit: responseUnit,
+      metadata: {},
+    }],
+    metadata: { analyte, responseUnit },
+  })
+  return createTemplateCollection(
+    [plate, sampleSheet, calibrationCurve, assayMatrix],
+    { preset: 'elisa-assay', ...(options.metadata ?? {}) }
+  )
+}
+
+export function createFlowCytometryAssayCollection(
+  options: CreateFlowCytometryAssayCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const markers = options.markers ?? ['CD3', 'CD4', 'CD8']
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const flowPanel = createFlowCytometryPanelTemplate({
+    markers,
+    instrument: options.instrument ?? 'Flow cytometer',
+    includeDefaultControls: options.includeDefaultControls,
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: options.features ?? flowPanel.data.markers.map(marker => ({
+      id: marker.id,
+      name: `${marker.marker}+ cells`,
+      type: 'cell',
+      unit: '%',
+      metadata: { marker: marker.marker, fluorophore: marker.fluorophore },
+    })),
+  })
+  return createTemplateCollection(
+    [sampleSheet, flowPanel, assayMatrix],
+    { preset: 'flow-cytometry-assay', ...(options.metadata ?? {}) }
+  )
+}
+
+export function createWesternBlotAssayCollection(
+  options: CreateWesternBlotAssayCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const sampleRecords = presetSampleRecords(options.samples ?? ['Control', 'Treatment'])
+  const loadingControl = options.loadingControl ?? 'ACTB'
+  const targetNames = (options.targets ?? ['Target protein']).map(target =>
+    typeof target === 'string' ? target : target.name ?? target.id
+  )
+  const featureNames = loadingControl && !targetNames.includes(loadingControl)
+    ? [...targetNames, loadingControl]
+    : targetNames
+  const sampleSheet = createSampleSheetTemplate({ samples: sampleRecords })
+  const reagentList = createReagentListTemplate({
+    reagents: [
+      { id: 'primary-antibody', name: 'Primary antibody', kind: 'antibody', storageCondition: '4C' },
+      { id: 'secondary-antibody', name: 'Secondary antibody', kind: 'antibody', storageCondition: '4C' },
+      { id: 'lysis-buffer', name: 'Lysis buffer', kind: 'buffer', storageCondition: '4C' },
+      { id: 'blocking-buffer', name: 'Blocking buffer', kind: 'buffer', storageCondition: '4C' },
+      { id: 'wash-buffer', name: 'TBST wash buffer', kind: 'buffer', storageCondition: 'RT' },
+      { id: 'substrate', name: 'Detection substrate', kind: 'reagent', storageCondition: '4C' },
+    ],
+    metadata: { assay: 'western-blot' },
+  })
+  const protocol = createProtocolStepsTemplate({
+    steps: [
+      { id: 'lyse-samples', type: 'addition', name: 'Lyse samples', duration: 30 },
+      { id: 'run-gel', type: 'custom', name: 'Run SDS-PAGE', duration: 90 },
+      { id: 'transfer', type: 'transfer', name: 'Transfer to membrane', duration: 60 },
+      { id: 'block', type: 'incubation', name: 'Block membrane', duration: 60 },
+      { id: 'primary-antibody', type: 'incubation', name: 'Primary antibody incubation', duration: 960 },
+      { id: 'secondary-antibody', type: 'incubation', name: 'Secondary antibody incubation', duration: 60 },
+      { id: 'detect', type: 'measurement', name: 'Detect and quantify bands', duration: 30 },
+    ],
+    metadata: { assay: 'western-blot' },
+  })
+  const assayMatrix = createAssayMatrixTemplate({
+    samples: sampleRecords.map(sample => ({
+      sampleId: sample.sampleId,
+      name: sample.name,
+      group: sample.group,
+      metadata: sample.metadata ?? {},
+    })),
+    features: featureNames.map((feature, index) => ({
+      id: idFromName(feature, `feature-${index + 1}`),
+      name: feature,
+      type: 'protein',
+      unit: 'relative intensity',
+      metadata: { loadingControl: feature === loadingControl },
+    })),
+    metadata: { assay: 'western-blot', loadingControl },
+  })
+  return createTemplateCollection(
+    [sampleSheet, reagentList, protocol, assayMatrix],
+    { preset: 'western-blot-assay', ...(options.metadata ?? {}) }
+  )
+}
+
+export function createBioTemplatePresetCollection(
+  name: 'wellplate-screen',
+  options?: CreateWellPlateScreenCollectionOptions
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollection(
+  name: 'qpcr-expression',
+  options?: CreateQpcrExpressionCollectionOptions
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollection(
+  name: 'lcms-batch',
+  options?: CreateLcmsBatchCollectionOptions
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollection(
+  name: 'elisa-assay',
+  options?: CreateElisaAssayCollectionOptions
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollection(
+  name: 'flow-cytometry-assay',
+  options?: CreateFlowCytometryAssayCollectionOptions
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollection(
+  name: 'western-blot-assay',
+  options?: CreateWesternBlotAssayCollectionOptions
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollection(
+  name: string,
+  options?:
+    | CreateWellPlateScreenCollectionOptions
+    | CreateQpcrExpressionCollectionOptions
+    | CreateLcmsBatchCollectionOptions
+    | CreateElisaAssayCollectionOptions
+    | CreateFlowCytometryAssayCollectionOptions
+    | CreateWesternBlotAssayCollectionOptions
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollection(
+  name: TemplatePresetId | string,
+  options:
+    | CreateWellPlateScreenCollectionOptions
+    | CreateQpcrExpressionCollectionOptions
+    | CreateLcmsBatchCollectionOptions
+    | CreateElisaAssayCollectionOptions
+    | CreateFlowCytometryAssayCollectionOptions
+    | CreateWesternBlotAssayCollectionOptions = {}
+): TemplateCollectionEnvelope {
+  const preset = getBioTemplatePresetInfo(name)
+  if (!preset) {
+    throw new Error(`Unknown template preset '${name}'.`)
+  }
+  if (preset.name === 'wellplate-screen') {
+    return createWellPlateScreenCollection(options as CreateWellPlateScreenCollectionOptions)
+  }
+  if (preset.name === 'qpcr-expression') {
+    return createQpcrExpressionCollection(options as CreateQpcrExpressionCollectionOptions)
+  }
+  if (preset.name === 'lcms-batch') {
+    return createLcmsBatchCollection(options as CreateLcmsBatchCollectionOptions)
+  }
+  if (preset.name === 'elisa-assay') {
+    return createElisaAssayCollection(options as CreateElisaAssayCollectionOptions)
+  }
+  if (preset.name === 'flow-cytometry-assay') {
+    return createFlowCytometryAssayCollection(options as CreateFlowCytometryAssayCollectionOptions)
+  }
+  if (preset.name === 'western-blot-assay') {
+    return createWesternBlotAssayCollection(options as CreateWesternBlotAssayCollectionOptions)
+  }
+  throw new Error(`Unknown template preset '${name}'.`)
+}
+
+export type BioTemplateControlValues = Record<string, unknown>
+
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'wellplate-screen',
+  values: BioTemplateControlValues
+): CreateWellPlateScreenCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'qpcr-expression',
+  values: BioTemplateControlValues
+): CreateQpcrExpressionCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'lcms-batch',
+  values: BioTemplateControlValues
+): CreateLcmsBatchCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'elisa-assay',
+  values: BioTemplateControlValues
+): CreateElisaAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'flow-cytometry-assay',
+  values: BioTemplateControlValues
+): CreateFlowCytometryAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: 'western-blot-assay',
+  values: BioTemplateControlValues
+): CreateWesternBlotAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+):
+  | CreateWellPlateScreenCollectionOptions
+  | CreateQpcrExpressionCollectionOptions
+  | CreateLcmsBatchCollectionOptions
+  | CreateElisaAssayCollectionOptions
+  | CreateFlowCytometryAssayCollectionOptions
+  | CreateWesternBlotAssayCollectionOptions
+export function bioTemplatePresetControlValuesToOptions(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+):
+  | CreateWellPlateScreenCollectionOptions
+  | CreateQpcrExpressionCollectionOptions
+  | CreateLcmsBatchCollectionOptions
+  | CreateElisaAssayCollectionOptions
+  | CreateFlowCytometryAssayCollectionOptions
+  | CreateWesternBlotAssayCollectionOptions {
+  const preset = getBioTemplatePresetInfo(name)
+  if (!preset) {
+    throw new Error(`Unknown template preset '${name}'.`)
+  }
+
+  if (preset.name === 'wellplate-screen') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      plateName: readString(values.plateName, 'Screen plate'),
+      plateFormat: readPlateFormat(values.plateFormat, 96),
+      unit: readString(values.unit, 'uM'),
+      replicates: readInteger(values.replicates, 3),
+    }
+  }
+
+  if (preset.name === 'qpcr-expression') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      targets: readStringList(values.targets, ['ACTB', 'GAPDH']),
+      chemistry: readString(values.chemistry, 'sybr') as CreateQpcrPlateTemplateOptions['chemistry'],
+      format: readPlateFormat(values.plateFormat, 96),
+      includeNoTemplateControls: readBoolean(values.includeNoTemplateControls, true),
+      replicates: readInteger(values.replicates, 3),
+      instrument: readOptionalString(values.instrument),
+    }
+  }
+
+  if (preset.name === 'lcms-batch') {
+    return {
+      samples: readStringList(values.sampleNames, ['S001', 'S002']),
+      features: readStringList(values.featureNames, ['Glucose', 'Lactate']),
+      instrument: readString(values.instrument, 'LC-MS'),
+      method: readString(values.method, 'Default method'),
+      includeQc: readBoolean(values.includeQc, true),
+    }
+  }
+
+  if (preset.name === 'elisa-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      analyte: readString(values.analyte, 'Analyte'),
+      standardConcentrations: readNumberList(values.standardConcentrations, [1000, 100, 10, 1]),
+      unit: readString(values.unit, 'pg/mL'),
+      responseUnit: readString(values.responseUnit, 'OD450'),
+      plateName: readString(values.plateName, 'ELISA plate'),
+      plateFormat: readPlateFormat(values.plateFormat, 96),
+    }
+  }
+
+  if (preset.name === 'flow-cytometry-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      markers: readStringList(values.markers, ['CD3', 'CD4', 'CD8']),
+      features: readStringList(values.featureNames, ['CD3+ cells', 'CD4+ cells', 'CD8+ cells']),
+      instrument: readString(values.instrument, 'Flow cytometer'),
+      includeDefaultControls: readBoolean(values.includeDefaultControls, true),
+    }
+  }
+
+  if (preset.name === 'western-blot-assay') {
+    return {
+      samples: readStringList(values.sampleNames, ['Control', 'Treatment']),
+      targets: readStringList(values.targets, ['Target protein']),
+      loadingControl: readString(values.loadingControl, 'ACTB'),
+    }
+  }
+
+  throw new Error(`Unknown template preset '${name}'.`)
+}
+
+export function createBioTemplatePresetCollectionFromControls(
+  name: 'wellplate-screen',
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollectionFromControls(
+  name: 'qpcr-expression',
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollectionFromControls(
+  name: 'lcms-batch',
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollectionFromControls(
+  name: 'elisa-assay',
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollectionFromControls(
+  name: 'flow-cytometry-assay',
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollectionFromControls(
+  name: 'western-blot-assay',
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollectionFromControls(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope
+export function createBioTemplatePresetCollectionFromControls(
+  name: TemplatePresetId | string,
+  values: BioTemplateControlValues
+): TemplateCollectionEnvelope {
+  const options = bioTemplatePresetControlValuesToOptions(name, values)
+  return createBioTemplatePresetCollection(name, options)
+}
+
+export function createTemplateCollection(
+  templates: Array<BioTemplateEnvelope<unknown>>,
+  metadata?: Record<string, unknown>
+): TemplateCollectionEnvelope {
+  const collection: TemplateCollection = {}
+  for (const template of templates) {
+    assertGenericTemplateEnvelope(template)
+    const templateId = template.template_id
+    if (collection[templateId]) {
+      throw new Error(`Duplicate template_id '${templateId}' in template collection.`)
+    }
+    collection[templateId] = template
+  }
+
+  return metadata === undefined
+    ? { [TEMPLATE_COLLECTION_KEY]: collection }
+    : { [TEMPLATE_COLLECTION_KEY]: collection, metadata }
+}
+
+export function extractTemplateCollection(value: unknown): TemplateCollection {
+  if (isEnvelope<unknown>(value)) {
+    assertGenericTemplateEnvelope(value)
+    return { [value.template_id]: value }
+  }
+  if (!isRecord(value)) {
+    throw new Error('Template collection payload must be an object.')
+  }
+
+  const rawCollection = value[TEMPLATE_COLLECTION_KEY]
+  if (rawCollection === undefined) {
+    return {}
+  }
+  if (!isRecord(rawCollection)) {
+    throw new Error('Template collection must be an object.')
+  }
+
+  const collection: TemplateCollection = {}
+  for (const [templateId, template] of Object.entries(rawCollection)) {
+    assertGenericTemplateEnvelope(template)
+    if (template.template_id !== templateId) {
+      throw new Error(
+        `Template collection key '${templateId}' does not match envelope template_id '${template.template_id}'.`
+      )
+    }
+    collection[templateId] = template
+  }
+  return collection
+}
+
+export function ensureTemplateFromCollection<TTemplate extends BioTemplateEnvelope<unknown>>(
+  value: unknown,
+  templateId: TemplateId | string
+): TTemplate {
+  const collection = extractTemplateCollection(value)
+  const template = collection[templateId]
+  if (!template) {
+    throw new Error(`Template '${templateId}' was not found in template collection.`)
+  }
+  assertTemplateEnvelope(template, templateId)
+  return template as TTemplate
+}
+
+export function assertTemplateEnvelope<TData>(
+  value: unknown,
+  templateId: TemplateId | string
+): asserts value is BioTemplateEnvelope<TData> {
+  assertGenericTemplateEnvelope(value)
+  if (value.template_id !== templateId) {
+    throw new Error(`Expected template_id '${templateId}', got '${String(value.template_id)}'.`)
+  }
+}
+
+export function ensureTemplateEnvelope<TTemplate extends BioTemplateEnvelope<unknown>>(
+  value: unknown,
+  templateId: TemplateId | string
+): TTemplate {
+  assertTemplateEnvelope(value, templateId)
+  return value as TTemplate
+}
+
+export function getTemplateData<TData>(
+  template: BioTemplateEnvelope<TData> | TData,
+  templateId?: TemplateId | string
+): TData {
+  if (isEnvelope<TData>(template)) {
+    if (templateId) assertTemplateEnvelope<TData>(template, templateId)
+    return template.data
+  }
+  return template
+}
+
+export function validatePlateMapData(data: PlateMapTemplateData): void {
+  if (!Array.isArray(data.plates) || data.plates.length === 0) {
+    throw new Error('Plate-map template requires at least one plate.')
+  }
+  const sampleIds = new Set(data.samples.map(sample => sample.id))
+  if (sampleIds.size !== data.samples.length) {
+    throw new Error('Plate-map sample ids must be unique.')
+  }
+  for (const plate of data.plates) {
+    for (const [wellId, well] of Object.entries(plate.wells)) {
+      if (well.id !== wellId) {
+        throw new Error(`Well key '${wellId}' does not match well id '${well.id}'.`)
+      }
+      if (well.sampleType && !sampleIds.has(well.sampleType)) {
+        throw new Error(`Well '${well.id}' references unknown sample '${well.sampleType}'.`)
+      }
+    }
+  }
+}
+
+export function validateSampleSheetData(data: SampleSheetTemplateData): void {
+  if (!Array.isArray(data.samples) || data.samples.length === 0) {
+    throw new Error('Sample-sheet template requires at least one sample.')
+  }
+  const sampleIds = new Set(data.samples.map(sample => sample.sampleId))
+  if (sampleIds.size !== data.samples.length) {
+    throw new Error('Sample-sheet sample ids must be unique.')
+  }
+  for (const group of data.groups) {
+    for (const sampleId of group.samples) {
+      if (!sampleIds.has(sampleId)) {
+        throw new Error(`Group '${group.name}' references unknown sample '${sampleId}'.`)
+      }
+    }
+  }
+}
+
+export function validateSamplePrepData(data: SamplePrepTemplateData): void {
+  if (!data.protocolName) {
+    throw new Error('Sample-prep template requires protocolName.')
+  }
+  if (!Array.isArray(data.steps) || data.steps.length === 0) {
+    throw new Error('Sample-prep template requires at least one step.')
+  }
+  const stepIds = new Set(data.steps.map(step => step.id))
+  if (stepIds.size !== data.steps.length) {
+    throw new Error('Sample-prep step ids must be unique.')
+  }
+  const orders = new Set(data.steps.map(step => step.order))
+  if (orders.size !== data.steps.length) {
+    throw new Error('Sample-prep step orders must be unique.')
+  }
+  for (const step of data.steps) {
+    if (!step.id || !step.name) {
+      throw new Error('Sample-prep steps require id and name.')
+    }
+    if (step.order < 0) {
+      throw new Error(`Sample-prep step '${step.id}' has a negative order.`)
+    }
+    if (!step.volumeUnit) {
+      throw new Error(`Sample-prep step '${step.id}' requires volumeUnit.`)
+    }
+    if (step.inputVolume !== undefined && step.inputVolume < 0) {
+      throw new Error(`Sample-prep step '${step.id}' has a negative input volume.`)
+    }
+    if (step.outputVolume !== undefined && step.outputVolume < 0) {
+      throw new Error(`Sample-prep step '${step.id}' has a negative output volume.`)
+    }
+    if (step.durationMin !== undefined && step.durationMin < 0) {
+      throw new Error(`Sample-prep step '${step.id}' has a negative duration.`)
+    }
+    if (!step.sourceSampleId && !step.destinationSampleId && !step.reagentId) {
+      throw new Error(`Sample-prep step '${step.id}' requires a source, destination, or reagent.`)
+    }
+  }
+}
+
+export function validateDoseResponseData(data: DoseResponseTemplateData): void {
+  if (!Array.isArray(data.compounds) || data.compounds.length === 0) {
+    throw new Error('Dose-response template requires at least one compound.')
+  }
+  if (!data.unit) {
+    throw new Error('Dose-response template requires a unit.')
+  }
+  if (data.replicates < 1) {
+    throw new Error('Dose-response replicates must be at least 1.')
+  }
+  for (const compound of data.compounds) {
+    if (compound.concentrations.length === 0) {
+      throw new Error(`Compound '${compound.name}' requires at least one concentration.`)
+    }
+    if (compound.concentrations.some(value => value < 0)) {
+      throw new Error(`Compound '${compound.name}' has a negative concentration.`)
+    }
+  }
+}
+
+export function validateCalibrationCurveData(data: CalibrationCurveTemplateData): void {
+  if (!data.analyte) {
+    throw new Error('Calibration-curve template requires an analyte.')
+  }
+  if (!data.xUnit) {
+    throw new Error('Calibration-curve template requires xUnit.')
+  }
+  if (!data.responseUnit) {
+    throw new Error('Calibration-curve template requires responseUnit.')
+  }
+  if (!Array.isArray(data.points) || data.points.length === 0) {
+    throw new Error('Calibration-curve template requires at least one point.')
+  }
+  if (data.acceptance.minRSquared < 0 || data.acceptance.minRSquared > 1) {
+    throw new Error('Calibration-curve minRSquared must be between 0 and 1.')
+  }
+  if (data.acceptance.standardTolerancePercent < 0 || data.acceptance.qcTolerancePercent < 0) {
+    throw new Error('Calibration-curve tolerances cannot be negative.')
+  }
+
+  const pointIds = new Set(data.points.map(point => point.id))
+  if (pointIds.size !== data.points.length) {
+    throw new Error('Calibration-curve point ids must be unique.')
+  }
+  const orders = new Set(data.points.map(point => point.order))
+  if (orders.size !== data.points.length) {
+    throw new Error('Calibration-curve point orders must be unique.')
+  }
+
+  let standards = 0
+  for (const point of data.points) {
+    if (!point.id || !point.level) {
+      throw new Error('Calibration-curve points require id and level.')
+    }
+    if (!point.unit) {
+      throw new Error(`Calibration-curve point '${point.id}' requires unit.`)
+    }
+    if (point.order < 0) {
+      throw new Error(`Calibration-curve point '${point.id}' has a negative order.`)
+    }
+    if (point.concentration < 0) {
+      throw new Error(`Calibration-curve point '${point.id}' has a negative concentration.`)
+    }
+    if ((point.role === 'standard' || point.role === 'qc') && point.concentration <= 0) {
+      throw new Error(`Calibration-curve point '${point.id}' requires positive concentration.`)
+    }
+    if (point.replicate < 1) {
+      throw new Error(`Calibration-curve point '${point.id}' replicate must be at least 1.`)
+    }
+    if (point.role === 'standard' && point.include) {
+      standards += 1
+    }
+  }
+
+  if (standards < 2) {
+    throw new Error('Calibration-curve template requires at least two included standards.')
+  }
+  if (data.acceptance.requireBlank && !data.points.some(point => point.role === 'blank')) {
+    throw new Error('Calibration-curve template requires a blank point when requireBlank is true.')
+  }
+}
+
+export function validateTimeCourseData(data: TimeCourseTemplateData): void {
+  if (!Array.isArray(data.timepoints) || data.timepoints.length === 0) {
+    throw new Error('Time-course template requires at least one time point.')
+  }
+  if (!Array.isArray(data.conditions) || data.conditions.length === 0) {
+    throw new Error('Time-course template requires at least one condition.')
+  }
+  const timepointIds = new Set(data.timepoints.map(timepoint => timepoint.id))
+  if (timepointIds.size !== data.timepoints.length) {
+    throw new Error('Time-course time point ids must be unique.')
+  }
+  const conditionIds = new Set(data.conditions.map(condition => condition.id))
+  if (conditionIds.size !== data.conditions.length) {
+    throw new Error('Time-course condition ids must be unique.')
+  }
+  const sampleIds = new Set(data.samples.map(sample => sample.sampleId))
+  if (sampleIds.size !== data.samples.length) {
+    throw new Error('Time-course sample ids must be unique.')
+  }
+  for (const sample of data.samples) {
+    if (!timepointIds.has(sample.timepointId)) {
+      throw new Error(`Sample '${sample.sampleId}' references unknown time point.`)
+    }
+    if (!conditionIds.has(sample.conditionId)) {
+      throw new Error(`Sample '${sample.sampleId}' references unknown condition.`)
+    }
+  }
+}
+
+export function validateProtocolStepsData(data: ProtocolStepsTemplateData): void {
+  if (!Array.isArray(data.steps) || data.steps.length === 0) {
+    throw new Error('Protocol-steps template requires at least one step.')
+  }
+  const stepIds = new Set(data.steps.map(step => step.id))
+  if (stepIds.size !== data.steps.length) {
+    throw new Error('Protocol-steps ids must be unique.')
+  }
+  const orders = new Set(data.steps.map(step => step.order))
+  if (orders.size !== data.steps.length) {
+    throw new Error('Protocol-steps orders must be unique.')
+  }
+  for (const step of data.steps) {
+    if (!step.id) {
+      throw new Error('Protocol step id is required.')
+    }
+    if (!step.name) {
+      throw new Error(`Protocol step '${step.id}' requires a name.`)
+    }
+    if (step.duration !== undefined && step.duration < 0) {
+      throw new Error(`Protocol step '${step.id}' has a negative duration.`)
+    }
+    if (step.order < 0) {
+      throw new Error(`Protocol step '${step.id}' has a negative order.`)
+    }
+  }
+}
+
+export function validateAssayMatrixData(data: AssayMatrixTemplateData): void {
+  if (!Array.isArray(data.samples) || data.samples.length === 0) {
+    throw new Error('Assay-matrix template requires at least one sample.')
+  }
+  if (!Array.isArray(data.features) || data.features.length === 0) {
+    throw new Error('Assay-matrix template requires at least one feature.')
+  }
+  const sampleIds = new Set(data.samples.map(sample => sample.sampleId))
+  if (sampleIds.size !== data.samples.length) {
+    throw new Error('Assay-matrix sample ids must be unique.')
+  }
+  const featureIds = new Set(data.features.map(feature => feature.id))
+  if (featureIds.size !== data.features.length) {
+    throw new Error('Assay-matrix feature ids must be unique.')
+  }
+  const measurementIds = new Set<string>()
+  for (const measurement of data.measurements) {
+    const key = `${measurement.sampleId}:${measurement.featureId}`
+    if (measurementIds.has(key)) {
+      throw new Error(`Duplicate assay measurement for '${key}'.`)
+    }
+    measurementIds.add(key)
+    if (!sampleIds.has(measurement.sampleId)) {
+      throw new Error(`Measurement references unknown sample '${measurement.sampleId}'.`)
+    }
+    if (!featureIds.has(measurement.featureId)) {
+      throw new Error(`Measurement references unknown feature '${measurement.featureId}'.`)
+    }
+  }
+}
+
+export function validateReagentListData(data: ReagentListTemplateData): void {
+  if (!Array.isArray(data.reagents) || data.reagents.length === 0) {
+    throw new Error('Reagent-list template requires at least one reagent.')
+  }
+  const reagentIds = new Set(data.reagents.map(reagent => reagent.id))
+  if (reagentIds.size !== data.reagents.length) {
+    throw new Error('Reagent-list reagent ids must be unique.')
+  }
+  for (const reagent of data.reagents) {
+    if (!reagent.id) {
+      throw new Error('Reagent-list reagent id is required.')
+    }
+    if (!reagent.name) {
+      throw new Error(`Reagent '${reagent.id}' requires a name.`)
+    }
+    if (reagent.stockLevel !== undefined && reagent.stockLevel < 0) {
+      throw new Error(`Reagent '${reagent.id}' has a negative stock level.`)
+    }
+  }
+}
+
+export function validateFlowCytometryPanelData(data: FlowCytometryPanelTemplateData): void {
+  if (!Array.isArray(data.markers) || data.markers.length === 0) {
+    throw new Error('Flow-cytometry panel template requires at least one marker.')
+  }
+  const markerIds = new Set(data.markers.map(marker => marker.id))
+  if (markerIds.size !== data.markers.length) {
+    throw new Error('Flow-cytometry panel marker ids must be unique.')
+  }
+  const controlIds = new Set(data.controls.map(control => control.id))
+  if (controlIds.size !== data.controls.length) {
+    throw new Error('Flow-cytometry panel control ids must be unique.')
+  }
+  for (const marker of data.markers) {
+    if (!marker.id) {
+      throw new Error('Flow-cytometry panel marker id is required.')
+    }
+    if (!marker.marker) {
+      throw new Error(`Flow-cytometry panel marker '${marker.id}' requires a marker name.`)
+    }
+  }
+  for (const control of data.controls) {
+    if (!control.id) {
+      throw new Error('Flow-cytometry panel control id is required.')
+    }
+    if (!control.name) {
+      throw new Error(`Flow-cytometry panel control '${control.id}' requires a name.`)
+    }
+    if (control.markerId && !markerIds.has(control.markerId)) {
+      throw new Error(`Flow-cytometry panel control '${control.id}' references unknown marker '${control.markerId}'.`)
+    }
+  }
+}
+
+export function validateInstrumentRunData(data: InstrumentRunTemplateData): void {
+  if (!Array.isArray(data.methods) || data.methods.length === 0) {
+    throw new Error('Instrument-run template requires at least one method.')
+  }
+  if (!Array.isArray(data.items) || data.items.length === 0) {
+    throw new Error('Instrument-run template requires at least one run item.')
+  }
+  const methodIds = new Set(data.methods.map(method => method.id))
+  if (methodIds.size !== data.methods.length) {
+    throw new Error('Instrument-run method ids must be unique.')
+  }
+  for (const method of data.methods) {
+    if (!method.id || !method.name) {
+      throw new Error('Instrument-run methods require id and name.')
+    }
+  }
+  const itemIds = new Set(data.items.map(item => item.id))
+  if (itemIds.size !== data.items.length) {
+    throw new Error('Instrument-run item ids must be unique.')
+  }
+  const orders = new Set(data.items.map(item => item.order))
+  if (orders.size !== data.items.length) {
+    throw new Error('Instrument-run item orders must be unique.')
+  }
+  for (const item of data.items) {
+    if (!item.id) {
+      throw new Error('Instrument-run items require id.')
+    }
+    if (!methodIds.has(item.methodId)) {
+      throw new Error(`Instrument-run item '${item.id}' references unknown method '${item.methodId}'.`)
+    }
+    if (item.kind === 'sample' && !item.sampleId) {
+      throw new Error(`Instrument-run sample item '${item.id}' requires sampleId.`)
+    }
+    if (item.order < 0) {
+      throw new Error(`Instrument-run item '${item.id}' has a negative order.`)
+    }
+    if (item.injectionVolume !== undefined && item.injectionVolume < 0) {
+      throw new Error(`Instrument-run item '${item.id}' has a negative injection volume.`)
+    }
+    if (item.expectedDurationMin !== undefined && item.expectedDurationMin < 0) {
+      throw new Error(`Instrument-run item '${item.id}' has a negative expected duration.`)
+    }
+  }
+}
+
+export function validateQpcrPlateData(data: QpcrPlateTemplateData): void {
+  if (!Array.isArray(data.samples) || data.samples.length === 0) {
+    throw new Error('qPCR plate template requires at least one sample.')
+  }
+  if (!Array.isArray(data.targets) || data.targets.length === 0) {
+    throw new Error('qPCR plate template requires at least one target.')
+  }
+  if (!Array.isArray(data.reactions) || data.reactions.length === 0) {
+    throw new Error('qPCR plate template requires at least one reaction.')
+  }
+  const sampleIds = new Set(data.samples.map(sample => sample.sampleId))
+  if (sampleIds.size !== data.samples.length) {
+    throw new Error('qPCR plate sample ids must be unique.')
+  }
+  const targetIds = new Set(data.targets.map(target => target.id))
+  if (targetIds.size !== data.targets.length) {
+    throw new Error('qPCR plate target ids must be unique.')
+  }
+  const reactionIds = new Set(data.reactions.map(reaction => reaction.id))
+  if (reactionIds.size !== data.reactions.length) {
+    throw new Error('qPCR plate reaction ids must be unique.')
+  }
+  const wellIds = new Set(data.reactions.map(reaction => reaction.wellId))
+  if (wellIds.size !== data.reactions.length) {
+    throw new Error('qPCR plate reaction wells must be unique.')
+  }
+  for (const reaction of data.reactions) {
+    assertWellInFormat(reaction.wellId, data.format)
+    if (!reaction.id) {
+      throw new Error('qPCR reaction id is required.')
+    }
+    if (!reaction.targetId || !targetIds.has(reaction.targetId)) {
+      throw new Error(`qPCR reaction '${reaction.id}' references unknown target '${reaction.targetId}'.`)
+    }
+    if (reaction.sampleId && !sampleIds.has(reaction.sampleId)) {
+      throw new Error(`qPCR reaction '${reaction.id}' references unknown sample '${reaction.sampleId}'.`)
+    }
+    if (reaction.controlKind === 'sample' && !reaction.sampleId) {
+      throw new Error(`qPCR sample reaction '${reaction.id}' requires sampleId.`)
+    }
+    if (reaction.replicate < 1) {
+      throw new Error(`qPCR reaction '${reaction.id}' replicate must be at least 1.`)
+    }
+    if (reaction.cq !== undefined && reaction.cq !== null && reaction.cq < 0) {
+      throw new Error(`qPCR reaction '${reaction.id}' has a negative Cq.`)
+    }
+    if (reaction.quantity !== undefined && reaction.quantity !== null && reaction.quantity < 0) {
+      throw new Error(`qPCR reaction '${reaction.id}' has a negative quantity.`)
+    }
+  }
+}
+
+function normalizeCompound(compound: CompoundDoseSeries): CompoundDoseSeries {
+  return {
+    ...compound,
+    concentrations: [...compound.concentrations].sort((a, b) => b - a),
+    metadata: compound.metadata ?? {},
+  }
+}
+
+function normalizeCalibrationAcceptance(
+  acceptance?: Partial<CalibrationAcceptance>,
+  requireBlank = true
+): CalibrationAcceptance {
+  return {
+    minRSquared: acceptance?.minRSquared ?? 0.99,
+    standardTolerancePercent: acceptance?.standardTolerancePercent ?? 15,
+    qcTolerancePercent: acceptance?.qcTolerancePercent ?? 20,
+    requireBlank: acceptance?.requireBlank ?? requireBlank,
+    metadata: acceptance?.metadata ?? {},
+  }
+}
+
+function normalizeCalibrationPoint(
+  point: CalibrationPointInput,
+  unit: string,
+  order: number,
+  index: number
+): CalibrationPoint {
+  const role = point.role ?? 'standard'
+  const level = point.level || `${role.charAt(0).toUpperCase()}${role.slice(1)} ${index + 1}`
+  return {
+    id: point.id || idFromName(level, `${role}-${index + 1}`),
+    order: point.order ?? order,
+    role,
+    level,
+    concentration: point.concentration ?? 0,
+    unit: point.unit || unit,
+    expectedResponse: point.expectedResponse,
+    response: point.response,
+    replicate: point.replicate ?? 1,
+    include: point.include ?? true,
+    status: point.status ?? 'planned',
+    metadata: point.metadata ?? {},
+  }
+}
+
+function normalizeSampleRecord(sample: SampleRecord): SampleRecord {
+  return {
+    ...sample,
+    metadata: sample.metadata ?? {},
+  }
+}
+
+function presetSampleRecords(samples: Array<string | SampleRecord>): SampleRecord[] {
+  return samples.map((sample, index) => {
+    if (typeof sample !== 'string') return normalizeSampleRecord(sample)
+    return {
+      sampleId: sampleIdFromName(sample, index),
+      name: sample,
+      metadata: {},
+    }
+  })
+}
+
+function normalizeSamplePrepStep(
+  step: SamplePrepStepInput,
+  prepType: SamplePrepStep['type'],
+  volumeUnit: string,
+  order: number,
+  index: number
+): SamplePrepStep {
+  const type = step.type ?? prepType
+  const sourceSampleId = step.sourceSampleId
+  const name = step.name || `Prepare ${sourceSampleId ?? index + 1}`
+  return {
+    id: step.id || idFromName(name, `${type}-${index + 1}`),
+    order: step.order ?? order,
+    type,
+    name,
+    sourceSampleId,
+    sourcePlateId: step.sourcePlateId,
+    sourceWellId: step.sourceWellId,
+    destinationSampleId: step.destinationSampleId,
+    destinationPlateId: step.destinationPlateId,
+    destinationWellId: step.destinationWellId,
+    reagentId: step.reagentId,
+    inputVolume: step.inputVolume,
+    outputVolume: step.outputVolume,
+    volumeUnit: step.volumeUnit || volumeUnit,
+    durationMin: step.durationMin,
+    status: step.status ?? 'planned',
+    metadata: step.metadata ?? {},
+  }
+}
+
+function normalizeControl(control: ControlDefinition): ControlDefinition {
+  return {
+    ...control,
+    metadata: control.metadata ?? {},
+  }
+}
+
+function normalizeTimePoint(timepoint: TimePoint): TimePoint {
+  return {
+    ...timepoint,
+    metadata: timepoint.metadata ?? {},
+  }
+}
+
+function normalizeCondition(condition: TimeCourseCondition): TimeCourseCondition {
+  return {
+    ...condition,
+    metadata: condition.metadata ?? {},
+  }
+}
+
+function normalizeProtocolStep(
+  step: Partial<ProtocolStepRecord> & { name: string },
+  index: number
+): ProtocolStepRecord {
+  return {
+    id: step.id ?? idFromName(step.name, `step-${index + 1}`),
+    type: step.type ?? 'custom',
+    name: step.name,
+    description: step.description,
+    duration: step.duration,
+    status: step.status ?? 'pending',
+    parameters: step.parameters ?? {},
+    order: step.order ?? index,
+    metadata: step.metadata ?? {},
+  }
+}
+
+function normalizeAssaySample(sample: AssaySample): AssaySample {
+  return {
+    ...sample,
+    metadata: sample.metadata ?? {},
+  }
+}
+
+function normalizeAssayFeature(feature: AssayFeature): AssayFeature {
+  return {
+    ...feature,
+    metadata: feature.metadata ?? {},
+  }
+}
+
+function normalizeReagent(reagent: ReagentTemplateInput): ReagentRecord {
+  return {
+    ...reagent,
+    expiryDate: normalizeDateString(reagent.expiryDate),
+    kind: reagent.kind ?? 'reagent',
+    metadata: reagent.metadata ?? {},
+  }
+}
+
+function normalizeDateString(value: Date | string | null | undefined): string | undefined {
+  if (value === undefined || value === null) return undefined
+  return value instanceof Date ? value.toISOString() : value
+}
+
+function normalizeFlowMarker(
+  marker: Partial<FlowPanelMarker> & { marker: string },
+  index: number
+): FlowPanelMarker {
+  return {
+    id: marker.id ?? idFromName(marker.marker, `marker-${index + 1}`),
+    marker: marker.marker,
+    fluorophore: marker.fluorophore ?? 'unassigned',
+    detector: marker.detector,
+    clone: marker.clone,
+    reagentId: marker.reagentId,
+    purpose: marker.purpose ?? 'phenotype',
+    compensationRequired: marker.compensationRequired ?? true,
+    metadata: marker.metadata ?? {},
+  }
+}
+
+function normalizeFlowControl(
+  control: Partial<FlowPanelControl> & { name: string },
+  index: number
+): FlowPanelControl {
+  return {
+    id: control.id ?? idFromName(control.name, `control-${index + 1}`),
+    name: control.name,
+    kind: control.kind ?? 'other',
+    markerId: control.markerId,
+    required: control.required ?? true,
+    metadata: control.metadata ?? {},
+  }
+}
+
+function normalizeInstrumentMethod(
+  method: Partial<InstrumentMethod> & { name?: string },
+  fallbackInstrument?: string
+): InstrumentMethod {
+  const name = method.name || method.id || 'Default method'
+  return {
+    id: method.id || idFromName(name, 'method-1'),
+    name,
+    instrument: method.instrument ?? fallbackInstrument,
+    acquisitionMode: method.acquisitionMode,
+    metadata: method.metadata ?? {},
+  }
+}
+
+function normalizeInstrumentRunItem(
+  item: Partial<InstrumentRunItem> & { name?: string; sampleId?: string },
+  defaultMethodId: string,
+  fallbackOrder: number,
+  index: number
+): InstrumentRunItem {
+  const kind = item.kind ?? 'sample'
+  const sampleId = item.sampleId || (kind === 'sample'
+    ? idFromName(item.name ?? `Sample ${index + 1}`, `sample-${index + 1}`)
+    : undefined)
+  const label = item.name ?? sampleId ?? kind
+  return {
+    id: item.id || idFromName(label, `${kind}-${index + 1}`),
+    order: item.order ?? fallbackOrder,
+    kind,
+    sampleId,
+    name: item.name,
+    methodId: item.methodId || defaultMethodId,
+    vial: item.vial,
+    plateId: item.plateId,
+    wellId: item.wellId,
+    injectionVolume: item.injectionVolume,
+    expectedDurationMin: item.expectedDurationMin,
+    status: item.status ?? 'planned',
+    metadata: item.metadata ?? {},
+  }
+}
+
+function normalizeQpcrSample(sample: QpcrSample): QpcrSample {
+  return {
+    ...sample,
+    metadata: sample.metadata ?? {},
+  }
+}
+
+function normalizeQpcrTarget(target: QpcrTarget): QpcrTarget {
+  return {
+    ...target,
+    metadata: target.metadata ?? {},
+  }
+}
+
+function defaultFlowControls(markers: FlowPanelMarker[]): FlowPanelControl[] {
+  return [
+    {
+      id: 'unstained',
+      name: 'Unstained',
+      kind: 'unstained',
+      required: true,
+      metadata: {},
+    },
+    ...markers
+      .filter(marker => marker.compensationRequired)
+      .map(marker => ({
+        id: `${marker.id}-single-stain`,
+        name: `${marker.marker} single stain`,
+        kind: 'single-stain' as const,
+        markerId: marker.id,
+        required: true,
+        metadata: {},
+      })),
+  ]
+}
+
+function createAssaySampleLookup(samples: AssaySample[]): Map<string, string> {
+  const lookup = new Map<string, string>()
+  for (const sample of samples) {
+    addLookupAlias(lookup, sample.sampleId, sample.sampleId)
+    if (sample.name) {
+      addLookupAlias(lookup, sample.name, sample.sampleId)
+      addLookupAlias(lookup, idFromName(sample.name, sample.sampleId), sample.sampleId)
+    }
+  }
+  return lookup
+}
+
+function createAssayFeatureLookup(features: AssayFeature[]): Map<string, string> {
+  const lookup = new Map<string, string>()
+  for (const feature of features) {
+    addLookupAlias(lookup, feature.id, feature.id)
+    addLookupAlias(lookup, feature.name, feature.id)
+    addLookupAlias(lookup, idFromName(feature.name, feature.id), feature.id)
+  }
+  return lookup
+}
+
+function addLookupAlias(lookup: Map<string, string>, alias: string, value: string): void {
+  if (!lookup.has(alias)) {
+    lookup.set(alias, value)
+  }
+}
+
+function wellIdsForFormat(format: number): string[] {
+  const dimensions = PLATE_DIMENSIONS[format]
+  if (!dimensions) {
+    throw new Error(`Unsupported plate format '${format}'.`)
+  }
+  const [rows, cols] = dimensions
+  return Array.from({ length: rows }, (_, row) =>
+    Array.from({ length: cols }, (_col, col) => `${rowLabel(row)}${col + 1}`)
+  ).flat()
+}
+
+function assertWellInFormat(wellId: string, format: number): void {
+  const dimensions = PLATE_DIMENSIONS[format]
+  if (!dimensions) {
+    throw new Error(`Unsupported plate format '${format}'.`)
+  }
+  const match = /^([A-Z]+)([1-9][0-9]*)$/.exec(wellId.toUpperCase())
+  if (!match) {
+    throw new Error(`Invalid well id '${wellId}'.`)
+  }
+  const row = rowIndex(match[1])
+  const col = Number(match[2]) - 1
+  const [rows, cols] = dimensions
+  if (row < 0 || col < 0 || row >= rows || col >= cols) {
+    throw new Error(`Well '${wellId}' is outside a ${format}-well plate.`)
+  }
+}
+
+function rowLabel(index: number): string {
+  let label = ''
+  let current = index
+  while (true) {
+    label = String.fromCharCode(65 + (current % 26)) + label
+    current = Math.floor(current / 26) - 1
+    if (current < 0) return label
+  }
+}
+
+function rowIndex(label: string): number {
+  return [...label].reduce((value, char) => value * 26 + char.charCodeAt(0) - 64, 0) - 1
+}
+
+function assertGenericTemplateEnvelope(value: unknown): asserts value is BioTemplateEnvelope<unknown> {
+  if (!isRecord(value)) {
+    throw new Error('Template envelope must be an object.')
+  }
+  if (typeof value.template_id !== 'string' || value.template_id.length === 0) {
+    throw new Error('Template envelope requires a template_id string.')
+  }
+  if (typeof value.template_version !== 'string' || value.template_version.length === 0) {
+    throw new Error('Template envelope requires a template_version string.')
+  }
+  if (!isRecord(value.data)) {
+    throw new Error('Template envelope data must be an object.')
+  }
+  if ('metadata' in value && !isRecord(value.metadata)) {
+    throw new Error('Template envelope metadata must be an object.')
+  }
+}
+
+function isEnvelope<TData>(value: unknown): value is BioTemplateEnvelope<TData> {
+  return isRecord(value) && 'template_id' in value && 'data' in value
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function readStringList(value: unknown, fallback: string[]): string[] {
+  if (Array.isArray(value)) {
+    const items = value.map(item => String(item).trim()).filter(Boolean)
+    return items.length ? items : fallback
+  }
+  if (typeof value === 'string') {
+    const items = value.split(',').map(item => item.trim()).filter(Boolean)
+    return items.length ? items : fallback
+  }
+  return fallback
+}
+
+function readNumberList(value: unknown, fallback: number[]): number[] {
+  const rawItems = Array.isArray(value)
+    ? value
+    : typeof value === 'string'
+      ? value.split(',')
+      : []
+  const items = rawItems
+    .map(item => Number(String(item).trim()))
+    .filter(item => Number.isFinite(item))
+  return items.length ? items : fallback
+}
+
+function readString(value: unknown, fallback: string): string {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback
+}
+
+function readOptionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined
+}
+
+function readInteger(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return Number.isFinite(parsed) ? Math.max(1, Math.round(parsed)) : fallback
+}
+
+function readBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback
+}
+
+function readPlateFormat(value: unknown, fallback: WellPlateFormat): WellPlateFormat {
+  const parsed = typeof value === 'number'
+    ? value
+    : typeof value === 'string'
+      ? Number(value)
+      : Number.NaN
+  return parsed in PLATE_DIMENSIONS ? (parsed as WellPlateFormat) : fallback
+}
+
+function sampleIdFromName(name: string, index: number): string {
+  return idFromName(name, `sample-${index + 1}`)
+}
+
+function compoundIdFromName(name: string, index: number): string {
+  return idFromName(name, `compound-${index + 1}`)
+}
+
+function idFromName(name: string, fallback: string): string {
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+  return slug || fallback
+}
+
+function timepointId(value: number, unit: string, index: number): string {
+  const raw = Number.isInteger(value)
+    ? String(value)
+    : String(value).replace(/0+$/, '').replace(/\.$/, '')
+  const token = raw.replace('.', 'p')
+  return token ? `t${token}-${unit}` : `timepoint-${index + 1}`
+}