# Versioning and Compatibility

## Why This Exists

The IR needs a schema marker and a small semantic version to prevent compiler/resolver mismatches, but Shellops does not need migration machinery before the IR becomes a public interchange format.

## Producers

- **Parser lowering:** writes `$schema: "shellops-ir"` and `ir_version: "1.0"` on every IR unit.
- **Engine release process:** decides when a new schema marker is required.

## Consumers

- **Resolver and emitter:** reject unknown schema markers.
- **Tests and fixtures:** pin expected IR shape during implementation.
- **Future external tooling:** may eventually require stable migration policy.

## Current Decision

```json
{
  "$schema": "shellops-ir",
  "ir_version": "1.0"
}
```

The compiler, resolver, and emitter ship in one binary and evolve in lockstep. The version uses two components:

- **Major:** breaking shape or semantic changes.
- **Minor:** additive fields, new object roles, new decorator roles, new branch clause roles, or new optional metadata.

No patch component is needed while IR is an internal compiler contract. Patch-level behavior belongs to the engine release version, not the IR schema.

## Allowed Within `1.x`

- Adding optional fields.
- Refining docs before implementation hardens a field.
- Adding new roles (decorator, binding, condition, branch clause, or payload item roles) for later build tiers.
- Adding resolver-owned metadata sections.
- Replacing unimplemented planning sketches with implemented shapes before external stability is promised.

## Requires `2.0`

- Removing or renaming fields after they are implemented and documented as consumed.
- Changing semantics of an existing statement or value shape.
- Changing type interpretation in a way that makes previously valid IR invalid.
- Publishing IR as a third-party tool contract and then breaking that contract.

## Explicitly Not Stable Yet

- Exact JSON Schema artifact path.
- Resolver-enriched metadata shape.
- Machine-output diagnostic envelope.
- Any field documented as future target state but not yet implemented in the engine.

## Invariants

- Unknown `$schema` is an error.
- Missing `$schema` is an error for IR consumers.
- Missing or unsupported `ir_version` is an error for IR consumers.
- Consumers accept only the major version they implement. Minor support may be exact or range-based once external consumers exist.
- No migration layer is planned until external consumers exist.
- Project language versioning and IR schema versioning are related but not the same thing.

## Design References

- [strategies/versioning](../strategies/versioning.md) owns the broader language and release compatibility policy.
- [tier-consumers](./tier-consumers.md) identifies which build tiers can depend on each part of the IR.
- [ir_schema](../ir_schema.md) is the canonical human-readable IR contract for now.
