# Concepts

> Patches, versions, base model compatibility, evidence states, sealed held-out suites and the regression suite.

Source: https://retoque.xyz/docs/concepts
Markdown: https://retoque.xyz/docs/md/concepts

A handful of terms carry most of the meaning in Retoque. The [Glossary](https://retoque.xyz/docs/glossary) has short definitions of the rest.

## Patch

A patch is a named fix for one task on one base model, such as `ledger-tool-call`. Technically it is a LoRA adapter, stored as `adapter_model.safetensors` with its PEFT `adapter_config.json`. It sits next to the base checkpoint and is applied at load time. It never changes the base weights.

A patch slug uses lowercase letters, digits and hyphens, up to 64 characters.

## Version

A version is one immutable package of a patch, written `slug@semver`, such as `ledger-tool-call@1.0.0`. It has its own manifest, signature, evaluation report and license terms. The CLI always asks for an explicit version. There is no implicit "latest".

Published files never change. If an install directory already exists with a different manifest, the CLI refuses to overwrite it.

Public routes and pages only show versions in these states:

| State | Meaning |
| --- | --- |
| `PUBLISHED` | Offered for new licenses and downloads. |
| `DEPRECATED` | Still downloadable by license holders. A newer version is preferred. |
| `WITHDRAWN` | No new licenses. The evidence stays public. Existing license holders can still download it unless their license was suspended. |

Before publication a version moves through `CANDIDATE`, `EVALUATED` and `VERIFIED_FOR_SCOPE`, which only its creator and reviewers can see.

## Base model compatibility

A patch is trained and evaluated against one Hugging Face repository at one full commit hash. The manifest records that pair along with the sha256 of the weights, of `tokenizer.json` and of the chat template.

When you install, the CLI compares your `--model` reference with the manifest and gets one of three outcomes:

| Outcome | When | What happens |
| --- | --- | --- |
| `SUPPORTED_EXACT` | Same repository and the same full commit. | Installs. |
| `UNKNOWN_UNTESTED` | Same repository, but the revision is a branch or tag, which can move. Also when the patch changes special tokens. | Refused unless you pass `--experimental-override`. |
| `INCOMPATIBLE` | A different repository or a different full commit. | Refused unless you pass `--experimental-override`. |

Unknown is never treated as compatible. An override prints a warning and is recorded as `experimentalOverride: true` in `retoque.lock`. Other sizes in the same family, quantized variants and merged weights are not supported.

## Evidence states

Each version carries exactly one evidence state. The packager assigns the starting state from the held-out numbers and the thresholds written into the manifest. Only an operator can move a version to verified.

| State | Meaning |
| --- | --- |
| `VERIFIED_FOR_SCOPE` | An operator reproduced the held-out result and checked rights and regressions. |
| `IMPROVED_ON_SCOPE` | Held-out improvement under the declared protocol. Not yet operator-verified. |
| `EVALUATED` | Metrics exist. Improvement is not established. |
| `EXPERIMENTAL` | Some signal, but not enough evidence for the declared threshold. |
| `DEGRADED` | Target or regression results got worse. |
| `WITHDRAWN` | Known bad or unsafe. The evidence stays public. |

The default thresholds are at least 10 percentage points of gain on the held-out suite and no more than 2 regression cases introduced. "Verified for scope" covers one task on one held-out suite and one checkpoint. It doesn't mean the model is better in general. See [Evaluation methodology](https://retoque.xyz/docs/evaluation).

## Sealed held-out suite

The held-out split is the only split a published version may cite. Its cases come from template families that never appear in training or validation, and they are not published, so nobody, including Retoque, can tune a later version against them. The report publishes the suite's sha256 digest, the aggregate counts and per-field error counts instead. Reviewers with access can reproduce the run.

Cases shown publicly on a patch page come from the validation split. They were visible during development, so they are examples of behaviour, not proof of it.

## Regression suite

`general-regression-v1` is a fixed set of 60 cases spread across six families of unrelated behaviour: arithmetic, capital cities, uppercasing, reversing a list, echoing a word, and extracting contact details into JSON with a different schema from the patch's task. It is graded by exact match. A regression is introduced when the base model passed a case and the patched model failed it. Every report lists the count.

## Entitlement and license

A license is permission to use one version under its written terms. An entitlement is Retoque's record that you hold one, and it is what the download route checks. See [Licenses and entitlements](https://retoque.xyz/docs/licenses).

## Registry key

A registry key starts with `rtq_` and authenticates the CLI to the Retoque registry for entitlement checks, download tickets and opt-in install reports. It is not a model API key.

## Lockfile

`retoque install` and `retoque rollback` write `retoque.lock` in the current directory. It pins each patch to exact package, manifest and adapter digests, the publisher key and the base revision, so a project can record which bytes it runs. Commit it.