API Compatibility

Mirrored from docs/api-compatibility.md in the repository, 2026-08-05. The repo copy is authoritative for anything CI-cited (exact commands, workflow files, versions) — this page exists so the wiki is self-contained, but re-sync it from the source if the two drift.

API compatibility policy

The stable pipeline wire API is platform-factory.dev/v1, exposed by the Go package api/v1. The plugin protocol has its own stable v1 version and lifecycle.

The supported Go SDK lives under sdk/: sdk/pipeline exposes pipeline loading and analysis, while sdk/microvm exposes both microVM configuration and the backend-neutral VMM lifecycle. sdk/plugin provides the reference Go runtime and the stable, language-neutral extension protocol. The historical api/pipeline, api/microvm, api/vmm, and api/plugin imports are deprecated forwarding shims whose type aliases remain assignment-compatible with the SDK.

Native implementations are deliberately not public SDK packages. KVM, HVF, and WHPX live under internal/hypervisor/{kvm,hvf,whpx}; authenticated guest channels live in internal/guest; boot bundles and durable machine state live in internal/runtime. Product code must depend on the SDK contracts instead of importing an implementation package.

Within a stable major version:

• existing JSON fields keep their names, types, and meaning;
• new fields are optional and default to the previous behavior;
• enum values are never repurposed;
• accepted documents remain accepted with the same observable DAG, canonical fingerprint, and cache-key semantics;
• security fixes may reject input only when accepting it would violate a documented safety invariant.

v1alpha1 and v1beta1 pipeline documents remain accepted for migration. Their frozen JSON fixtures run through the same strict decoder and conformance engine as v1. Deprecation requires a release note and at least two minor releases of overlap. Removing a stable field or version requires a new major wire version.

The public conformance binary embeds validation, fingerprint, cache-key, and execution-backend vectors. Compatibility changes must update implementation code while preserving already shipped fixtures; historical fixtures must not be rewritten to make a breaking change pass.