EVOLUTION

Compatibility & migration

RAIQL 1.0 introduces the first explicit project/language compatibility contract. Existing 0.20 source remains valid; migration updates project metadata, plugin expectations and auditability rather than changing working source behind your back.

Three versions, three responsibilities

RAIQL now distinguishes the CLI/compiler release, the project schema version and the language contract used by a project.

raiql.config.json

{
  "version": "1.0",
  "languageVersion": "0.21",
  "compatibility": {
    "mode": "compatible",
    "pluginApi": "1"
  }
}

version controls project metadata, languageVersion records the language contract, and pluginApi pins the extension interface independently.

Inspect compatibility

terminal

raiql compatibility

The command checks project schema support, language compatibility, configured plugin API versions and registry plugin RAIQL ranges. It exits non-zero for incompatible contracts.

Migration preview

terminal

raiql migrate --dry-run
raiql migrate --check

--dry-run prints the plan without writing. --check is CI-friendly: it exits non-zero when the project still needs migration.

Apply migration

terminal

raiql migrate

RAIQL writes a backup of the previous config and a machine-readable migration report under .raiql/migrations/. The 0.21 migration keeps 0.20 source unchanged because the grammar is backward-compatible.

Generated compatibility manifest

Every generated project now includes raiql.compatibility.json containing the language contract, generating CLI, plugin API and core-output contract. This gives CI, plugins and future migration tooling a stable file to inspect without reverse-engineering generated source.

Strict mode

raiql.config.json

"compatibility": { "mode": "strict", "pluginApi": "1" }

Strict mode requires the project language contract to match the current compiler. Compatible mode allows supported older contracts and reports upgrade guidance instead.

Continue exploring RAIQLOpen the playground →