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. No 0.x component pair has a cross-version compatibility promise. The first v1 release will end that rule 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 protects contract shape and meaning. It does not freeze every pack, action, policy, or internal implementation. 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 reinterpret a frozen value. A strict schema change uses a new schema version. A wire change uses a new protocol version.

Component versions#

The product uses one semantic version. Runner and bridge binaries also have component release tags. The v1 release notes name 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 and MCP bridges for canary and rollback steps.

Deprecation and removal#

1. Release notes name 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 name 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 name the safe replacement.