Compatibility Policy

Karkain 1.2.0 defines what external developers may rely on between releases. This policy is governed by the formal SemVer policy (Semantic Versioning Policy (SemVer)) and the version-wise development plan (docs/audit/KARKAIN-VERSION-PLAN.md).

Guarantee levels

Guarantee levels

Level

Policy

Stable Core

Reliable. Changes are deliberate, documented in Release Notes, and accompanied by a regression test. A change to the published stable surface requires a documented justification and a migration note.

Experimental

May change between releases without notice. Read the specific Experimental or Release-Candidate Scope entry to know exactly why a surface is experimental.

Planned / Not Yet Implemented

No compatibility guarantee. Nothing in a plan is part of the API until a gate test exercises it through the real pipeline.

Release Candidate

Between the Beta 1 line and a release candidate, only release-blocking corrections (bugs, security, compatibility breaks, deterministic-correctness fixes) are made.

Karkain 1.2.0 versioning

The v1.2.0 Stable Build label applies from the v1.2.0 release (Sovereignty I). The v1.1.0 label applied from Phase 142; before that, 1.0.0 (v1.0.0, Phase 119), Beta 1 (v0.117.x) and Developer Preview (v0.115.x) carried the earlier lines. 1.0.x continues as the LTS line. The versioning convention is:

  • Karkain Compiler v1.2.0 (... Stable Build) — the current Stable line.

  • VERSION at the repository root: 1.2.0.

  • Patch releases within the 1.0 line stay 1.0.x (LTS).

Versioning

  • The minor version (0.x) signals the public-surface stability level.

  • Within a Beta line, patch levels are used for corrections.

  • Engine behavior: the Go front end and the self-hosted kcc engine share the same version identity and produce byte-identical output on the gated corpus. A divergence in a Implemented feature is a defect, reported through the issue tracker.

What is covered

What is not covered

  • Anything labeled Experimental or Planned.

  • The exact text of diagnostics, which may be reworded as long as the error-code contract is preserved.

  • Toolchain internals (IR formats, C emission details, cache layout).

Feedback on a breaking change

If you believe a documented stable behavior changed, open a bug report with the exact before/after behavior. Compatibility regressions are treated as release blockers during the Beta/RC preparation period (see Feature-Freeze Policy (Beta / Release-Candidate)).

See also

Release-Candidate Scope — the authoritative status matrix. Feature-Freeze Policy (Beta / Release-Candidate) — the temporary freeze policy. Stable API Snapshot (1.2.0) — the Beta API snapshot. Engine Compatibility — Go front end vs. kcc engine parity.