Versioning and upgrades

How Ownfold versions packages and persisted formats, validates compatibility, sequences upgrades, and preserves safe rollback paths.

Ownfold versions packages with Changesets and validates public TypeScript surfaces with API Extractor. Package SemVer and persisted-format versions are related but separate: upgrading a package does not automatically rewrite encrypted records, Recovery Kits, or device envelopes. Release maintainers must also follow the release checklist.

Persisted-format policy

PersistedFormatSupport from @ownfold/core is the machine-readable compatibility contract for the release. Each entry declares every readable version and the version emitted by new writes. The dedicated pnpm test:compatibility gate verifies that manifest against checked-in immutable cryptographic fixtures.

PersistedCryptoCapabilities.current is the parallel algorithm-suite contract. Before changing a writer suite, deploy a bridge release whose read list contains both old and new suites while its writer remains old. checkCompatibility must report bidirectional compatibility between the bridge and new writer release before rollout. Never negotiate an automatic downgrade from unauthenticated client input.

• Writers emit only the declared write version.
• Readers retain every declared read version.
• A new writer version must land with an ADR, strict parser, fixture, migration or compatibility path, documentation, and changeset.
• A readable version cannot be removed without a major package release and a documented migration that applications can complete before upgrading.
• Unknown future versions fail with a typed unsupported-version error. They are never guessed or silently downgraded.

The direct legacy X25519 CryptoKey stored by early browser builds is an explicit local-storage compatibility exception. It remains readable, while all new writes use ownfold.protected-device-private-key V1.

Upgrade procedure

1. Read the package changesets and persisted-format notes.
2. Back up the application database and retain the previously deployed application artifacts.
3. Apply database migrations before deploying code that requires them. Use the adapter-specific transaction and locking guidance.
4. Run pnpm test:compatibility, check cryptographic capabilities across every supported rolling deployment pair, run the shared adapter compliance suite, and run the host application’s own encrypted-record fixtures against a staging copy.
5. Deploy the server coordination layer before browser code when a release expands a transport contract. Existing readers must continue accepting the previous writer format during rollout.
6. Monitor typed transport, parser, recovery, device, and rotation errors. Never log Recovery Kits, encrypted payload contents, passwords, or decrypted values while diagnosing failures.

Rollback

Code rollback is safe only while the previous release can read every format already written by the new release. Before enabling a new writer version, verify this explicitly or use a server-controlled capability gate supplied by the host application. Database rollback must preserve encrypted blobs, device envelopes, recovery metadata, pairing state, rotation checkpoints, and revisions.

Do not restore an older database snapshot independently of encrypted application records. That can reintroduce revoked devices, stale key versions, or incomplete rotations. If compatibility is uncertain, stop writes, preserve current data, and investigate with metadata-only tooling.

Pre-1.0 stability

Public TypeScript APIs may still receive breaking changes before 1.0 and will be called out in Changesets. Persisted cryptographic formats are held to the stricter policy above from the first published beta: maintainers disappearing must not make already encrypted data undecipherable.