Skip to content

Fixed-cohort staged traffic (experimental)

StagedTraffic(pipe, promoted_version, rollout_id='stable-id', phases=[{'share': .1, 'units': ['stable-unit-id', ...], 'max_excess_loss': 0}, ...]) is an opt-in, single-owner router. The candidate must already have passed the pipeline's fresh stages and remain active. Each phase declares the entire finite cohort in advance, both deterministic hash-assigned arms must be nonempty, and IDs cannot repeat across phases. Owner declares exchangeable units and independently authenticates outcomes. These assumptions are not a sandbox or statistical certificate.

route(unit) writes the variant assignment durably BEFORE returning a version for the owner to execute. It never executes model/agent/deployment callbacks. Repeated routes and reconstruction with the same pipeline journal/configuration return the same assignment. Use persistent fsync nonrotating JSONL or synchronous FULL/EXTRA disk SQLite, outside batches. Memory/ephemeral storage refuses. Configuration is frozen; mutation or conflicting restart configuration refuses. One owner owns calls; concurrent multi-process routing/phase transitions are not supported.

observe(unit, loss, by='independent-source') requires an existing assignment, unique actual label and bounded loss [0,1]. It delegates to Pipeline.observe, preserving the proposal's expected effect alongside the actual version/outcome. Do not use admission as truth. An outcome is not interchangeable with a model estimate. This API does not discover missing outcomes or authenticate gold labels.

Explicit checkpoint() HOLDs until EVERY predeclared unit is labelled, including baseline, so selecting only fast/good labels cannot advance. At completion it records candidate mean loss minus baseline mean loss: greater than the predeclared max_excess_loss yields rollback, otherwise advance to the next frozen phase. This is a fixed-cohort DESCRIPTIVE gate, not an anytime confidence bound, causal proof or automatic deployment approval. There is no StreamPromise/e-process claim. Missing labels never pass.

Rollback stops routing; completion also refuses further routing. Owner handles the recorded recommendation, explicit deployment/revert and any further fresh checks. No automatic external publication, Pipeline target revert or full-traffic switch occurs. Restart reuses journaled decisions. Existing default Pipeline/ShipWatch behavior is unchanged.

Every checkpoint revalidates raw Pipeline.observe evidence, not merely the convenience helper's inputs. An outcome must name the earlier durable assignment record ID and match its change, current phase, frozen cohort unit and deterministic version; loss must be a finite [0,1] number. The assignment's journal sequence must precede the outcome. Duplicate unit labels or malformed/foreign evidence fail closed. Bare Pipeline.observe rows with only rollout/phase/unit/loss cannot advance a phase; they are rejected rather than treated as a complete labelled cohort.

Recovered assignments are centrally validated before both routing and checkpointing: exact integer phase/version, frozen cohort membership, deterministic arm, sequence after the plan and inside the journal head, record hash/ID, and unique phase-unit/sequence/ID. A validly journaled but invalid version is not executable. Recovered phase decisions also require the complete assigned outcomes that existed BEFORE their sequence and must exactly reproduce the fixed-cohort difference, label count and decision. A raw advance record cannot skip an unlabelled phase. These are consistency checks, not authentication against an owner able to forge independent ground truth.