# Error Essence — Versioning and Pinning

A consumer of this format is usually a **prompt**. Prompts fail silently: change a
field name under one and it does not throw, it just gets worse at its job, in a way
nobody notices until a customer does. That is the whole reason this format is versioned
and the version is mandatory rather than optional.

## The version is in the document

```json
{ "schemaVersion": "1.0.0", "...": "..." }
```

`schemaVersion` is `const` in the schema. A consumer can assert on it, and a producer
that changes shape without changing it has broken the contract, not evolved it.

## Semantics

Semver, with the classifications spelled out — the arguments are always at the edges.

### Patch — `1.0.0` → `1.0.1`

Documents are **byte-identical**. Only prose, examples, and clarifications that do not
change what a producer emits or a consumer may assume.

- fixing a typo in this specification
- adding a worked example
- clarifying wording that two implementers read differently — *provided* both readings
  produced the same document

### Minor — `1.0.0` → `1.1.0`

Additive. **A 1.0.x consumer keeps working unchanged.**

- a new **optional** field
- a new member in an enum documented as extensible: `hydration[].tool`,
  `breadcrumbs[].kind`, `changeCorrelations[].kind`
- a new hydration handle
- relaxing a constraint (a `maxLength` raised, a required field made optional — see the
  caveat below)

Consumers MUST ignore unknown enum members gracefully rather than failing. A consumer
that hard-fails on an unrecognised breadcrumb kind has opted out of minor upgrades.

> **The caveat on relaxing.** Making a required field optional is additive for a
> *producer* and breaking for a *consumer* that dereferences it. In this format that
> counts as **major**. The rule of thumb: if any correct 1.0.0 consumer could crash or
> silently mis-handle a valid 1.1.0 document, it is not minor.

### Major — `1.0.0` → `2.0.0`

Everything else:

- removing or renaming a field
- making an optional field required, or a required field optional
- narrowing a type (`string` → `enum`, widening `null` out of a union)
- changing the meaning of an existing value
- **changing the token budget in either direction** — the budget is the contract, and a
  consumer sizing its context window around 500 tokens is broken by 800 just as surely
  as by 300
- changing the trust-label vocabulary or the obligations attached to a label
- changing the reduction ladder's guarantees (e.g. no longer maintaining
  `hiddenFrameCount`)

## What a producer owes

1. **Serve at least the two most recent majors.** A customer's prompt library does not
   migrate on your release schedule.
2. **Let a caller request a version explicitly** — a header, a query parameter, a tool
   argument. The mechanism is unspecified; the capability is not.
3. **Reject an unknown version.** A request for `9.9.9` is an error, never a silent
   fallback to the newest. Silent fallback is how a pinned consumer discovers a major
   upgrade in production.
4. **Announce a deprecation before it lands**, with a date and a migration note.
5. **Never change a published version in place.** `1.0.0` means one thing forever. This
   is why the schema generator is covered by a drift test: a "small fix" to the zod
   schema silently republishes 1.0.0 as something else, and the test is what stops it.

## What a consumer owes

1. **Pin.** Ask for the version your prompts were written against.
2. **Assert `schemaVersion`** on receipt. It costs one comparison and turns a silent
   degradation into a loud failure.
3. **Ignore unknown fields.** Additive minors are the mechanism the format evolves by;
   a strict-mode parser opts out of it.
4. **Ignore unknown enum members gracefully** — treat an unrecognised
   `breadcrumbs[].kind` as opaque rather than dropping the breadcrumb.
5. **Do not infer from field order.** JSON objects are unordered; the generator's key
   order is stable for diff readability, not for parsing.

## URL pinning

The canonical `$id` carries the version:

```
https://spec.bucker.io/error-essence/1.0.0/schema.json
```

That URL is immutable. A newer schema gets a new URL; it never replaces an old one.

## History

| Version | Date | Change |
| --- | --- | --- |
| 1.0.0 | 2026-08 | Initial publication. Schema generated from the reference implementation; three worked examples; conformance checklist. |
| 2.0.0 | 2026-08 | The causal projection. **Removed** `suspectCommits`, `changeCorrelations`, `similarIssues`; **added** `causes` (ranked, entity-validated, each weight labelled `calibrated` or `prior`), `refusedCauses`, and the `sufficiency` receipt. Token budget UNCHANGED at 500 — deliberately, since changing it in either direction is itself a major and 2.0.0 is not spending its major on that. |

## Status of each version

| Version | Status | Served | Default for unpinned callers |
| --- | --- | --- | --- |
| 1.0.0 | Stable | Yes | **Yes** |
| 2.0.0 | Stable | Yes | No — opt in with an explicit pin |

2.0.0 is not the default. Promoting a default across a major breaks every consumer who
had not pinned yet, in the silent way this document opens by describing. 1.0.0 remains
the default until its deprecation is announced here with a date.
