Spec Experiments
Run controlled experiments on ContractSpec operations, gradually shift traffic, and roll back automatically when guardrails trip.
Define control + variants
import { SpecExperimentRegistry } from '@lssm-tech/lib.growth/spec-experiments';
const registry = new SpecExperimentRegistry().register({
target: { key: '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 '@lssm-tech/lib.growth/spec-experiments';
adapterContext.specVariantResolver = createSpecVariantResolver({
adapter,
resolveUserId: (ctx) => ctx.userId ?? ctx.organizationId ?? 'anon',
});Track outcomes + auto-rollback
import {
SpecExperimentAnalyzer,
SpecExperimentController,
} from '@lssm-tech/lib.growth/spec-experiments';
const analyzer = new SpecExperimentAnalyzer(tracker);
const controller = new SpecExperimentController({
registry,
analyzer,
onRollback: (target, evaluation) => notifyOps(target, evaluation.reasons),
});Deterministic bucketing
ExperimentRunner reuses the same hashing logic as growth experiments—every user sticks to a variant.
Multi-stage rollouts
Use `rolloutStages` to shift 1% → 10% → 50% → 100%. Guardrails trigger rollbacks automatically.