NovaSeal API Stability Guarantee

Status: Works today (ADR-0041, NovaSeal v0.12.15+)

This document defines the NovaSeal API stability contract, breaking-change definition, and versioning policy.

1. Stability Tiers

Surface Tier Policy
NovaSeal.seal(manifest) → SealBundle Stable No breaking changes without NOVASEAL_MAJOR increment
NovaSeal.verify(capsule_id, seal_dir) → VerificationResult Stable No breaking changes without NOVASEAL_MAJOR increment
SealBundle.dsse_envelope (bytes) Stable Format: DSSE per Sigstore spec; no changes without NOVASEAL_MAJOR
SealBundle.tsr (bytes) Stable Format: RFC 3161 DER; no changes without NOVASEAL_MAJOR
SealBundle.log_entry (dict) Stable Schema additions are backwards-compatible; removals require NOVASEAL_MAJOR
KeyConfig, SigningProfile dataclasses Stable Additive field additions OK; removals require NOVASEAL_MAJOR
load_signing_profile() return type Stable
VerificationResult fields Stable Additive only until NOVASEAL_MAJOR
Cap-004: ToolPermissionEvent schema Stable JSON Schema at schemas/tool-permission-event.schema.json
Cap-001: RedactionManifest schema Experimental OQ-01 unresolved; may change before legal-hold mode is removed
Cap-002: AnnexIVDocument schema Stable JSON Schema at schemas/annex-iv-document.schema.json
Internal modules (_engine.py, merkle.py) Internal No stability guarantee
CLI commands (nova verify, nova seal) Stable Flag renames require deprecation notice ≥1 minor version
SigningBackend Protocol (sign_digest/get_cert_der) Stable Implemented by LocalSigningBackend/AwsKmsSigningBackend/AzureKvSigningBackend/GcpKmsSigningBackend; new backends may be added additively
KeyWrappingBackend Protocol (wrap_key/unwrap_key/kek_ref, ADR-0185) Experimental Separate, additive capability protocol for envelope-encryption KEKs; live cloud backends verified only against SDK-contract fakes
X509SigningIdentity / verify_x509_signature (ADR-0055) Experimental Shipped v0.91.0 as a library API; not yet wired to novaseal.yaml/CLI, so its call surface may still change before that integration lands
Sigstore bundle output (nova seal sign --backend sigstore, ADR-0071) Tracks upstream spec The bundle is Sigstore's own v0.3 format, not a NovaFabric wire format — its stability follows the sigstore SDK's, independent of NOVASEAL_MAJOR
Checkpoint / witness cosigning (trust/novaseal/witness.py, ADR-0097) Experimental Library API only (no CLI); note format is a simplified C2SP tlog-checkpoint note, explicitly documented as subject to change (e.g. the deferred 4-byte key-hash disambiguation)

2. Versioning Policy

NovaSeal follows semantic versioning embedded within the NovaFabric package version (MAJOR.MINOR.PATCH).

An additional NOVASEAL_MAJOR counter tracks the cryptographic API version. It is a policy convention (currently 1) that governs the breaking-change rules below; it is not (yet) exposed as a code constant. The shipped version of record is the NovaFabric package version (novafabric.__version__); a future release may surface NOVASEAL_MAJOR as an explicit symbol in src/novafabric/trust/novaseal/__init__.py.

When to increment NOVASEAL_MAJOR

NOVASEAL_MAJOR MUST be incremented when:

  1. DSSE envelope format changes — e.g. new required header, payload encoding change.
  2. Signing algorithm change — e.g. Ed25519 → Ed448 or post-quantum algorithm.
  3. Merkle log format change — node hashing scheme, tree structure.
  4. SealBundle field removal or type change.
  5. VerificationResult field removal or type change that could cause a verifier to accept a previously-invalid seal or reject a previously-valid seal.
  6. ToolPermissionEvent schema version change (removing or renaming required fields).
  7. RedactionManifest schema version change (structural change, not additive).

NOVASEAL_MAJOR is NOT incremented for:

Migration path for NOVASEAL_MAJOR increments

When NOVASEAL_MAJOR is incremented:

  1. Announce the change in CHANGELOG.md under a ### Breaking Changes header.
  2. Provide a migration guide in docs/migrations/novaseal-vN-to-vM.md.
  3. The old format must remain verifiable for at least two NovaFabric minor releases (e.g. if NOVASEAL_MAJOR increments at v0.15, old seals must verify until v0.17).
  4. Add a seal_format_version field to SealBundle and VerificationResult to allow format detection.

3. Breaking Change Definition

A breaking change is any change that causes:

Changes that are NOT breaking:

4. Deprecation Process

Before removing or renaming any stable surface:

  1. Add a DeprecationWarning (Python standard) in the affected function/class.
  2. Document in CHANGELOG.md under ### Deprecated.
  3. Maintain the deprecated surface for at least one NovaFabric minor release cycle.
  4. Remove only in a NOVASEAL_MAJOR increment release.

5. Experimental Surfaces

Surfaces marked Experimental may change in any release without NOVASEAL_MAJOR increment. They are documented with # experimental or **experimental** in docstrings and this file.

Currently experimental:

6. References