Spec Experiments

Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip.

Define control + variants

import { SpecExperimentRegistry } from '@contractspec/lib.growth/spec-experiments';

const registry = new SpecExperimentRegistry().register({
  target: { name: 'billing.createInvoice', version: 4 },
  experiment: {
    key: 'billing.createInvoice.evolution',
    version: '1.0.0',
    goal: 'Reduce PO validation failures',
    primaryMetric: 'latency_ms',
    variants: [
      { id: 'control' },
      { id: 'po-required', description: 'Force PO field', weight: 1 },
    ],
  },
  control: BillingCreateInvoiceV4,
  variants: [
    { id: 'po-required', spec: BillingCreateInvoiceForAcme },
  ],
  rolloutStages: [0.01, 0.1, 0.5, 1],
  guardrails: { errorRateThreshold: 0.02, latencyP99ThresholdMs: 500 },
});

Attach to runtime

import { createSpecVariantResolver } from '@contractspec/lib.growth/spec-experiments';

adapterContext.specVariantResolver = createSpecVariantResolver({
  adapter,
  resolveUserId: (ctx) => ctx.userId ?? ctx.organizationId ?? 'anon',
});

Track outcomes + auto-rollback

import {
  SpecExperimentAnalyzer,
  SpecExperimentController,
} from '@contractspec/lib.growth/spec-experiments';

const analyzer = new SpecExperimentAnalyzer(tracker);
const controller = new SpecExperimentController({
  registry,
  analyzer,
  onRollback: (target, evaluation) => notifyOps(target, evaluation.reasons),
});