Compatibility and stability

Khora is 0.x. It may break. This page says when, how you find out, and what 1.0 is waiting for — because “pre-1.0, anything can change” is not a policy, it is the absence of one.

What 0.x promises

Within one release, everything. A program that compiles with one khora 0.3.0 build compiles with every 0.3.0 build, and the lockfile resolves the same way. Pin the toolchain and a build is reproducible.

[toolchain]
version = "0.3.0"

A pin that cannot be satisfied fails loudly. It never silently runs a different compiler — the toolchain shim hands over before argument parsing, and khora toolchain which tells you which build answered and why.

Between releases, nothing is guaranteed — but nothing breaks silently either:

• Every breaking change is in the changelog, under a Breaking heading, before anything else.
• A change that made a program silently wrong is listed under Breaking as well as Fixed, because code written around the old behaviour will behave differently now.
• Where a mechanical fix exists, the entry names it.

What counts as breaking

Surface	Breaking?
Language syntax and semantics	Yes
A std signature, type or behaviour	Yes
A std item’s removal or rename	Yes
Lockfile format	Yes
Manifest keys the toolchain requires	Yes
CLI flags and their meanings	Yes
Diagnostic wording	No
A new lint, or a lint’s default level	No
Compiler internals, IR, symbol names	No
Which fiber implementation is the default	Yes, today. It is meant to be unobservable and is not — see below
Anything under docs/ in the repository	No

A new lint can make khora check report something it did not report before. That is deliberate and is not treated as breaking: a lint tells you about code that was already wrong. Set its level in [lints] if you disagree.

The fiber backend is observable

The two backends do not agree about cancellation. Under KHORA_FIBERS=scheduler a fiber inside clock.sleep is woken by a cancellation and its sleep returns early; under the default thread backend the sleep runs to completion. On the same source that is a 350x difference in wall clock.

So the backend is not an implementation detail, and the default cannot change without a breaking-change note. Known limitations has the measurements.

Editions

There is no editions mechanism, and there will not be one until something needs it. An edition is a promise to maintain two languages at once, and a 0.x with three release candidates has no evidence that it is the right shape of promise.

khora.toml has no edition key. The question it looks like it would answer — which Khora builds this? — is answered by the toolchain table, which names a version that exists and selects the binary that runs.

What 1.0 is waiting for

1.0 means the surfaces in the table above stop changing without a major version. It is waiting on four things, none of which is a feature:

1. A bug-discovery rate that has flattened. The honest signal is not a feature list; it is how often a session aimed at known issues turns up something new. Recent sessions have still produced silent-wrongness bugs in trait dispatch and structured concurrency. Until that stops, a stability promise would be a promise to keep bugs.
2. The formal soundness review finished. All 282 unsafe blocks now name the invariant that makes them sound, and a gate step keeps it that way. What is missing is the other half: which test protects each invariant. The load-bearing ones say so; most do not. The soundness design note is where that lives.
3. The scheduler measured on Linux. Fibers are OS threads by default and the M:N scheduler is opt-in; that choice is settled for 0.3.0 and written up in the fibers design note. What is not settled is whether it should stay that way, and the missing evidence is the density claim on Linux — the reason the scheduler exists. The I/O backends underneath it are the other half of that question, and Linux now has epoll – a backend rather than a rewrite, with a poll fallback where the kernel will not open one. macOS wants kqueue, which is the same shape; Windows wants IOCP, which is not a backend swap because it is completion-based.
4. Use by people who did not write it. Nothing else substitutes for it, and it has not happened yet.

The known limitations page tracks the shorter-term version of the same list.

How language changes are decided

In the open, in an issue, before the code. Changes that alter what a program means are recorded in the roadmap or in a design note, with the argument rather than only the conclusion. CONTRIBUTING.md has the process.

One maintainer has final say. That is stated plainly rather than dressed as a committee, so you can judge the project’s bus factor for yourself.

Reporting a break

If an upgrade breaks a program and the changelog does not say it would, that is a bug in the changelog and worth reporting on its own. Include khora --version — it carries the commit and the target triple, which is usually enough to find the change that did it.