# Compatibility Policy

This document defines the public compatibility contract for `kernite`.

## Versioning

- `kernite` follows Semantic Versioning (SemVer).
- Public API contract changes are governed by major/minor/patch semantics.

## Stable Contract Surface

The following fields are part of the stable execute contract for v1:

- top-level: `ctx_id`, `message`, `data`
- decision payload: `data.decision`, `data.reason_codes`, `data.reasons`
- selection/evidence payload: `data.policy_selection_reason_code`, `data.policy`, `data.trace_hash`
- idempotency echo: `data.idempotency_key`

## Reason Code Stability

- Existing reason-code meanings must remain stable once released.
- New reason codes may be added in minor versions.
- Removing or re-defining existing reason code semantics requires a major version.
- Canonical v1 reason-code meanings are defined in `docs/conformance/v1/reason_codes_v1.json`.
- Implementations may enrich `details` payloads, but must not alter code semantics.

## Golden Vector Update Rules

- Canonical vector source is `docs/conformance/v1/execute_vectors.json`.
- `patch`/`minor` versions may only append vectors or additive optional fields.
- Mutating existing vector expectations requires a major version bump.
- If runtime behavior diverges intentionally, add a time-bounded allowlist entry in conformance tests with an explicit expiry date.

## Deprecation Window

- Contract fields may be marked deprecated in minor versions.
- Deprecated fields are removed only in a subsequent major version.
- A deprecation window and migration notes must be documented before removal.

## Conformance Vectors

- Canonical execute behavior is captured in `docs/conformance/v1/execute_vectors.json`.
- Every release should pass the conformance suite for all stable vectors.
- Conformance must compare:
  - `data.decision`
  - `data.reason_codes`
  - `data.reasons[*].code`
  - `data.policy_selection_reason_code`
  - `data.idempotency_key`
  - `data.trace_hash` (format and canonicalization contract)

## Compatibility Matrix

- Managed API versions should publish a compatibility mapping to `kernite` versions.
- If a managed API depends on a stricter contract, that dependency must be documented explicitly.

## Bootstrap Scope (0.1.x)

- Built-in domain policy defaults are intentionally removed from `evaluate_execute`.
- Policy selection is expected from external input via `policy_context.selected_policies`.
- For governed scopes, no matching selected policy is fail-closed:
  - decision: `denied`
  - reason code: `no_matching_policy`
- For non-governed scopes with no selected policy:
  - decision: `approved`
  - reason code: `out_of_scope_phase1`
- Governed scope can be declared by:
  - `policy_context.governed = true`
  - or a matching entry in `policy_context.governed_scopes`
