Pyvorin Rollout Playbook — Pilot to Production

Adopting Pyvorin across an organisation fails the same way most performance adoptions fail: a broad rollout decided on marketing numbers, followed by a quiet retreat when the promised speedups do not appear in production. This playbook is the narrower path. One CPU-bound service is chosen and proven with measured numbers; success criteria are written down before the rollout; expansion happens in stages with a rollback story at every step. It covers the technical sequence — pilot, proof, criteria, stages, rollback — and the organisational ones that decide whether the sequence survives contact with a real engineering org: training, governance, champions and a centre of enablement.

All product behaviour referenced below is verified against pyvorin-native 1.0.9. The metrics named as success criteria are the five adoption metrics documented on the measuring Pyvorin adoption page; this playbook is about when and in what order to apply them.

Step one: pick the pilot

Choose one service, and make it a CPU-bound one. The canonical benchmark table tells you exactly which workload shapes pay: numerical computing at a 10.91x category geomean, financial calculations at 13.53x, simulation at 13.1x, object manipulation at 42.28x. It is equally clear about the shapes that do not: string manipulation at 0.85x, parsing at 0.86x, web request handling at 0.97x, compression at 0.19x — workloads that live inside C library calls or drown in object churn. A pilot drawn from the first group starts with the odds in its favour; a pilot drawn from the second produces a loss and a narrative that kills the whole programme.

The right pilot has three further properties. Its hot path is pure-Python loops you can point at in a profile. It has a stable entrypoint function the benchmark harness can time. And its owners are willing to write down a target, because step three demands one. If no service meets all three, fix that first; a pilot chosen for political convenience rather than workload fit measures nothing except politics.

Step two: run the proof

The proof is a speed proof, run on the pilot's own hardware, and it follows the sequence on the how to run a speed proof page: baseline the service under CPython, compile the hot functions, measure the distribution rather than a single pass, and keep compile time separate from steady-state timing so amortisation is a visible decision. The working commands, all verified against the installed build:

python -m pyvorin support service/hot.py
python -m pyvorin bench service/hot.py --function entry --runs 10 --warmup 3
python -m pyvorin bench service/hot.py --function entry --json
python -m pyvorin compile service/hot.py --fail-on-fallback

The JSON report is the proof artefact: status, correct, fallback_used and fallback_reason tell you whether the function genuinely went native, and the timing block carries the median you will quote later. A COMPATIBILITY_EXECUTED status is not a slow success; it means the function never compiled, and the proof is not done until --explain-fallback has been read and the construct fixed or the function dropped from scope.

Two structural notes from the verified behaviour. Compile once, then let the disk cache carry the cost: a warm re-run reports compile_time: 0.000 ms, which is what production will see after the first call. And decide up front where compilation happens — at image build or service start — because the one-time compile cost belongs in deployment, not in a user's first request; the warm-up options are covered in the caching docs.

Step three: write success criteria before you expand

Three metrics decide whether the pilot graduates, all drawn from the verified adoption metrics:

Native-path coverage. The share of hot-path functions at COMPILED_FULL. Set the bar from the pilot's own support report, not from a brochure. A service whose hot path compiles fully at 60 per cent coverage has told you something different from one that compiles fully at 95 per cent, and both are useful data.
Benchmark deltas. The measured median speedup on the pilot's entrypoints against its CPython baseline. Anchor expectations honestly: the full canonical suite median is 1.35x with a 3.16x geomean, 54 of 71 workloads faster and 17 slower. A pilot target below the suite median is a workload-fit warning, not a target.
Cache hit rate. In CI and deploys, the fraction of compiles served from the disk cache at zero compile time. This is the metric that separates a working pipeline from one that pays full compile cost on every build; the mechanics and the keying scheme are on the artifact caching and CI caching pages.

Write the thresholds down, with the pilot's measured values attached, before stage two begins. Criteria written after the numbers arrive are descriptions, not criteria.

Step four: roll out in stages

Stage one — pilot to production. Ship the pilot service with the compiled hot path and the --fail-on-fallback gate in its own pipeline. Watch the fallback signals for a release cycle; the fallback deep dive explains how to read them. One service in production, measured honestly, is worth more than ten services promised.

Stage two — the adjacent services. Expand to the services that share the pilot's workload shape — the same profiling signature, the same loop-heavy code. Require each to pass the same proof before its rollout; do not inherit the pilot's numbers, because hardware and data differ.

Stage three — default-on for new code. Make the proof sequence part of the service template: a support report for every new hot module, a bench assertion in CI, and the compile gate on claimed-native files. At this stage adoption stops being a project and becomes hygiene.

Stage four — review. On a fixed cadence, re-run the proofs on the services that matter. Upgrades re-key every compiled artefact, so a pyvorin-native version bump is a natural re-measurement point: the old cache invalidates wholesale by design, and the new numbers either confirm the investment or tell you which functions have drifted into compatibility mode.

The organisational tracks

Technology rollouts die of organisational causes more often than technical ones. Four practices, run in parallel with the stages:

Training. One session for the whole engineering org on what the compiler does and does not take — the unsupported-construct list, the fallback semantics, the meaning of the four status words — and one deeper session for the teams in stages one and two on the diagnosis commands. The training material should be the docs themselves, run live: support, compile --explain-fallback, bench --json. Engineers who have watched a fallback reason appear in front of them diagnose their own code; engineers who only saw slides file tickets.

Champions. Name one engineer per service in stages one and two as the local owner of the proof artefacts. The champion's job is narrow: keep the bench assertions green, read the first fallback report, and escalate with data rather than anecdotes. This is a part-time duty attached to an existing role, not a new hire.

Governance. Two rules carry almost the whole load. Bench claims — any number quoted in a design doc, a PR description or a review — must come from bench --json output with correct: true, never from a single informal run. And fallback is an allowed outcome but a reportable one: a service running functions in compatibility mode is correct but unaccelerated, and its owners should know which functions those are. The measurement page's fallback-rate trend exists precisely for this review.

Centre of enablement. For larger orgs, one small group — often the platform team — owns the shared machinery: the CI cache keys, the pinned pyvorin-native version, the licence-state hygiene across runners, and the canonical set of proof artefacts. Services adopt; the centre maintains what they adopt onto. Skipping this works until the second version bump, and fails precisely then.

The rollback story

Rollback is unusually cheap, and saying exactly why is part of the pitch. Pyvorin compiles plain Python: there are no annotations in your source and no codegen your program depends on. Falling back to the pre-Pyvorin state is removing the compile step from deployment — the service then runs ordinary CPython, which is the same code it ran before, byte for byte. You do not need a migration branch, a data backfill or a flag day.

Within a running deployment the same property holds in miniature. Where the compiler cannot take a function, it runs the original Python under a recorded fallback rather than guessing, so the failure mode of an over-claimed rollout is lost speed, never wrong answers. A staged rollback is therefore: gate the compile step off for the affected service, confirm the service is green on plain CPython, and investigate at leisure. Keep the compiled cache directory versioned by toolchain in CI so an upgrade-triggered re-key cannot silently reintroduce full compile costs on the way back. Speed is what you are buying; reversibility is what makes the purchase safe.

A worked judgement call

The playbook says stages; the calendar says everything at once. Suppose three teams volunteer simultaneously in week one. The judgement call is to refuse two of them. A pilot's purpose is measurement under control, and three pilots produce three sets of hardware, three baselines and three narratives arriving together — which is how marketing numbers creep back in through the side door. Run one pilot to its written criteria, graduate it or kill it on the evidence, and let the queue form behind a process with a track record. Adoption velocity measured in weeks of staged proof beats adoption theatre measured in services touched.

Where to go next

Measuring Pyvorin adoption — the five metrics this playbook uses as success criteria, defined precisely.
How to run a speed proof — the step-by-step proof sequence for the pilot.
Caching compiled artifacts in CI — the cache-key scheme behind the cache hit rate criterion.
Benchmarks — the canonical workload table used to pick a CPU-bound pilot.

Last reviewed 24 July 2026 against pyvorin-native 1.0.9 installed at /root/pvfinal. Commands quoted were captured from real runs on 13 September 2026; benchmark figures are from the canonical table of the same date. Organisational practices are engineering guidance, not product behaviour.