Skip to content
ContractSpec
Start here
AI index

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.