Stability and compatibility¶
For a long-running pipeline, pin the pVisor version, record format, and agent version. Before upgrading, use representative tasks to verify execution, review, apply, and replay; keep the matching reader for old records.
Current readers check format versions. Verify each interface against its reading rules when upgrading.
Reading rules available today¶
| Interface | Current rule |
|---|---|
| CLI / Run TOML | Current --help/types define behavior; unknown fields reject; check changelog when upgrading |
| Run record / completion | New Run schema 2 requires completion protocol 1; missing committed completion yields Unknown after owner exit; schema 1 retains legacy reading rules |
| Run Bundle | New schema 5 requires a matching Run/Attempt completion receipt and Bundle digest; schema 4 remains readable under legacy rules; unknown versions reject; no automatic migration |
| Event / Journal | Formal version 5; old JSONL incompatible |
| Operation | Schema 1; unknown versions reject |
| Replay | sandbox-playback.result/v3; adapter versions pinned in the guide |
| Rust embedding API | Follows crate revision; CLI availability does not imply ABI/source compatibility |
These are implemented reading rules, not new long-term promises awaiting maintainer confirmation. Pin pVisor version/commit, record schemas, and validate representative tasks before upgrading.
Upgrade procedure¶
- Retain old Bundles, Journals, and capture rather than overwriting them.
- Run a fresh Job with the new version; check admission, output reading, and apply conflicts.
- Keep a compatible old reader for old records; do not remove schema fields to bypass checks.
- Record CLI/config/format/platform changes in the changelog. Maintainers still need to define deprecation windows.