Compatibility and deprecation

emisar is pre-1.0 today. Version 1.0 will freeze the public contracts used by deployed runners, clients, scripts, and saved configuration.

The v1 promise#

Pre-1.0, components move together — there is no compatibility promise between 0.x versions. The first v1 release ends that for the contracts on this page.

• 1.0.0 establishes the public compatibility baseline.
• A 1.x minor release can add compatible behavior.
• A patch release contains compatible fixes and documentation changes.
• A breaking contract change needs a new major version or a versioned successor.

The freeze covers contract shape and meaning — it does not freeze packs, actions, policies, or internal implementation, so new packs and optional fields can still be added.

Frozen public contracts#

The v1 freeze covers these operator and integration surfaces:

• The portal-to-runner WebSocket protocol and its message versions.
• Pack, action, catalog, trusted-manifest, runbook, and runner-config schemas.
• MCP transport revisions, tool names, tool inputs, and identifiers.
• OAuth metadata, endpoints, device authorization, and saved credentials.
• OIDC callback values, SCIM paths, resources, filters, and token behavior.
• Audit export parameters, fields, cursors, and CSV format.
• Runner and bridge commands, flags, configuration, and environment variables.
• Runner state files, installer inputs, release assets, and container image paths.
• The versioned registry tree and the runner registry facade paths.

Compatible changes#

A 1.x release can add a new optional field, command, endpoint, tool, pack, or action. Old clients must keep working without that addition.

A 1.x release does not rename, remove, narrow, or change the meaning of a frozen value. A breaking schema change ships as a new schema version, and a wire change as a new protocol version.

Component versions#

The product uses one semantic version, and the runner and bridge binaries also carry component release tags. The v1 release notes list the runner and bridge versions shipped with 1.0.0.

After v1 ships, later 1.x portals will keep the v1 wire and MCP contracts compatible. Check the supported minimum and recommended versions before each rollout. Use Upgrade runners for canary and rollback steps.

Deprecation and removal#

1. Release notes list the old contract, replacement, migration, affected versions, and earliest removal release.
2. emisar keeps the old contract for at least two minor releases or 12 months. The longer period applies.
3. Console, audit, CLI, and startup warnings show the replacement and removal release.
4. Both versions remain accepted during the window.
5. Removal happens in a major release and returns an actionable error.

A security issue can shorten the window when the old behavior is unsafe. Release notes must explain the exception and show the safe replacement.