Changing a standard type's encoding

Upgrading Jadpo never makes your stored data unreadable. A Jadpo release changes how a standard type is sent, stored or written as text only together with a reader for the old form and a release note. A golden file per type, built from its examples, pins every form, so a change can't pass unnoticed.

A value outlives the release that wrote it wherever it is kept: in a column, in an event waiting to be delivered, in a passkey, in a signed session cookie. Each of those records which encoding wrote it. So a release that changes a form reads what an earlier release kept with that release's reader, and an upgrade never strands it.

The encodings each release writes, as its release notes list them:

• What a golden file pins. For each valid example of the type: its canonical text (none for a type with no single text form, or for a secret value), the JSON the route codec writes, and each storage column's value as it is written into a statement, which is the value the runtime binds. Above them it records each column's suffix, PostgreSQL type and comment. A secret value's JSON is the redaction the codec writes, and a secret value is stored never. Feature and FeatureCollection are read and written through a program whose properties are { name }, as their examples' are, since their second type argument is always your app's own object. People's formats aren't pinned: CLDR's wording isn't an encoding, and no stored value holds it.
• One encoding number for a whole release, currently 1, not one per type. A row or a token holds values of many types, so one number says which reader each needs. A golden file records the encoding that last changed it. A form whose type's file records an encoding at or past the release's can't be rewritten, so changing a form means raising the encoding, and the release notes' row for that encoding must name every type whose file it changed. A new type, or an example added or dropped, changes no form. A type dropped from the release keeps failing the test, since a release keeps reading every type it wrote.
• Where the encoding is recorded: in a signed part's payload (enc); in jadpo_outbox.encoding for an event's payload, which a delivery reads it by; in jadpo_batch_runs.encoding for a batch run's saved values and key:; and in jadpo_passkeys.encoding for a passkey, which is stored as WebAuthnCredential's contract JSON (Encodings in system tables). A sealed value keeps its own version byte, which says how it is sealed, not how what it holds is written. An idempotency key's stored response is the bytes that were sent, read back as they were, and holds no encoding.
• What was kept before encodings were recorded is read as it was written, by the reader it was kept with: a signed part without enc, whose members are encoding 1's, and a passkey whose encoding is NULL, whose count is a number or its digits.
• An encoding this release doesn't know, a later release's, is never guessed at. A signed part with one opens nothing and the record is read, a passkey is refused, an event's delivery is parked and a batch run ends failed.
• An entity's own columns record no encoding. A form that changes their columns' types shows in the migration snapshot, so jadpo check asks for a migration. A form that changes what a column of the same type holds needs the release to provide the migration that rewrites stored values. No release has needed one yet.