Define procedure for supporting different versions of snapshots/sessions

[anders-kiaer]

[rubenthoms]

Persistence Versioning & Porting System - Design Proposal

Context

Webviz sessions (dashboards, module instances, ensembles, settings) are persisted to localStorage/CosmosDB as JSON, and individual modules persist their own settings/view state as opaque stringified JSON nested inside a session. Neither has any notion of a schema version today. Backward compatibility is currently handled ad hoc — e.g. PrivateWorkbenchSession.ts marks caseName, comparisonEnsembleCaseName, referenceEnsembleCaseName as optional with comments like // Optional for backward compat serialization – awaiting schema versioning. As modules and the framework evolve, older persisted sessions (in localStorage and in the CosmosDB-backed backend) need a real migration path instead of ad-hoc optional fields.

The goal is a versioning system with:

• Schemas that carry a version number.
• Chainable porting functions (version N → N+1) that can be run repeatedly until a document reaches the current version.
• A clear split between framework-level content (ported eagerly, in full, the moment a session is loaded — each historical version validated against its own frozen schema immediately before its porter runs, not just the final result checked at the end) and module-level state (ported lazily, independently, whenever that specific module instance's persistence logic runs — matching how module state is already deserialized independently per instance today).
• Porting logic written as pure, dependency-free functions (no React/jotai/DOM imports) so the exact same code can later be imported by a standalone batch service that migrates the whole database, without pulling in the browser app.

Scope of this task: build the shared infrastructure only (types, chain-port runner, registries, wiring into the existing frontend load paths) and land the first real migration (the three ad-hoc-optional fields above) as a concrete proof. The standalone batch-porting service itself is an explicit follow-up, not built here — but the infra must not need to change shape to support it later.

Design

1. Shared chain-porter runner (new, dependency-free)

New file: frontend/src/framework/utils/persistence/porting.ts — no React/jotai/DOM imports (Ajv itself is plain JS/Node-safe and already used the same way in deserialization.ts/ModuleInstanceSerializer.ts, so it's fine to depend on here too), so this file can be imported standalone by a future Node-based batch service.

Key refinement: each hop needs the frozen schema for the version it claims to be, not just a transform function. Without this, a chain would only validate the final (current-version) result — if a document's declared version doesn't actually match its shape (corruption, hand-edited data, a bug in an earlier porter), the porter function for that hop would crash on malformed input with a confusing, low-level error instead of a clear validation failure at the boundary. So each step carries both a schema (validates the input to that hop) and the port function:

import type { JTDSchemaType } from "ajv/dist/jtd";
import { Ajv } from "ajv/dist/jtd";

export type PortStep<TIn = unknown, TOut = unknown> = {
    schema: JTDSchemaType<TIn>;   // frozen schema describing this step's input (i.e. version v's shape)
    port: (data: TIn) => TOut;   // transforms version v -> v+1
};

export type PorterChain<TFinal = unknown> = {
    steps: PortStep[];           // steps[i] validates + ports version (minSupportedVersion + i) -> (+ i + 1)
    minSupportedVersion: number; // version of steps[0]'s input — see "retiring old steps" below
    currentVersion: number;      // derived by the builder as minSupportedVersion + steps.length
    currentSchema: JTDSchemaType<TFinal>; // validates the final result, including the no-op/current-version path
    /** Phantom marker, never set at runtime — exists only so assigning a built chain to a
     *  `PorterChain<TFinal>`-typed const checks that the last step's output really is TFinal (see 1.1). */
    _finalType?: TFinal;
};

export class PortingError extends Error {}

export class PortingValidationError extends Error {
    constructor(message: string, public readonly claimedVersion: number, public readonly errors: unknown) {
        super(message);
        this.name = "PortingValidationError";
    }
}

export class PortingTooOldError extends Error {
    constructor(message: string, public readonly claimedVersion: number, public readonly minSupportedVersion: number) {
        super(message);
        this.name = "PortingTooOldError";
    }
}

const ajv = new Ajv();

export function portToLatest<T = unknown>(data: unknown, storedVersion: number, chain: PorterChain): T {
    if (storedVersion > chain.currentVersion) {
        throw new PortingError(`Data version ${storedVersion} is newer than supported version ${chain.currentVersion}`);
    }
    if (storedVersion < chain.minSupportedVersion) {
        throw new PortingTooOldError(
            `Data version ${storedVersion} predates the oldest version this build can still port (${chain.minSupportedVersion}). ` +
                `This should only happen if the batch-porting service's guarantee was violated, or for client-owned data (e.g. ` +
                `localStorage) that was never touched by that service — see the caveat below.`,
            storedVersion,
            chain.minSupportedVersion,
        );
    }
    let result: unknown = data;
    for (let v = storedVersion; v < chain.currentVersion; v++) {
        const step = chain.steps[v - chain.minSupportedVersion];
        if (!step) throw new PortingError(`Missing porter for version ${v} -> ${v + 1}`);
        const validate = ajv.compile(step.schema);
        if (!validate(result)) {
            throw new PortingValidationError(
                `Data claiming to be version ${v} does not match version ${v}'s schema`,
                v,
                validate.errors,
            );
        }
        result = step.port(result);
    }

    const validateCurrent = ajv.compile(chain.currentSchema);
    if (!validateCurrent(result)) {
        throw new PortingValidationError(
            `Ported data does not match current version ${chain.currentVersion}'s schema`,
            chain.currentVersion,
            validateCurrent.errors,
        );
    }
    return result as T;
}

If storedVersion === currentVersion (the steady-state case once most data has been migrated), the historical-step loop body never runs, but the result is still validated against currentSchema. This makes portToLatest a complete boundary in its own right and prevents a future standalone batch service or new caller from accidentally omitting final validation. Existing outer validateContent/validateFull/per-component AJV calls may remain initially as defense in depth, but they are no longer required for the porter's correctness and can later be consolidated if profiling shows meaningful duplication. One generic runner is reused by both framework-content porting and module-state porting — no duplicated migration-walking or validation logic.

Authoring convention this implies: schemas and porters for past versions are immutable migration artifacts, not ordinary implementation files. When a version bump is needed, a repository command promotes the previously recorded current schema snapshot into a frozen v{n}.schema.json (or equivalent self-contained constant), creates a porter skeleton, and updates the integrity manifest. The developer then implements the pure v{n} -> v{n+1} porter, updates the live schema/type, adds golden before/after fixtures, and appends the step to the chain. Frozen schemas must not import mutable runtime schema fragments, and already-shipped porter implementations must not be edited in normal feature work. This is analogous to database migration tools keeping old migration files immutable — until an explicitly authorized retirement.

How portToLatest finds the correct starting point, and why the chain is NOT ever-growing: chain.steps[i] handles the hop from version minSupportedVersion + i to minSupportedVersion + i + 1. As long as nothing has been retired, minSupportedVersion is 0 and this is just direct indexing by version number — the loop starts at index storedVersion and walks forward, no search needed. But the chain must support retiring old steps: once the independent batch-porting service (a future follow-up, see Context) has migrated every document in the database past some version K, the porters for versions below K become permanently dead code on the backend-data path, and a developer can delete their frozen schema/porter files and raise minSupportedVersion to K, shrinking steps from the front. The v - chain.minSupportedVersion offset is what keeps indexing correct after such a prune — steps[0] no longer always means "port v0→v1", it means "port minSupportedVersion→minSupportedVersion + 1", whatever minSupportedVersion currently is. This is why the chain is a shrinking-and-growing window over version history, not a strictly ever-growing list: it grows by one step on every version bump, and may be pruned from the front once the batch service has confirmed no data below the new floor remains — but only on the backend-data path.

Important caveat — localStorage is not covered by that pruning guarantee. The batch-porting service (out of scope for this task) only ever touches backend-persisted sessions/snapshots in CosmosDB; it has no reach into a user's browser localStorage, which can contain arbitrarily old, never-saved-to-backend session data (e.g. a draft session left untouched for a long time). If a porter is retired because the backend is fully migrated, a sufficiently stale local session below the new minSupportedVersion will hit PortingTooOldError on load. Section 2 below adds an explicit write-back so that every local session gets durably upgraded to the current version the moment it's opened, which substantially narrows this window (only sessions never reopened at all across an entire version bump remain at risk) — but it doesn't eliminate it outright, since a session can still in principle sit unopened through a whole bump-then-retire cycle. This needs a deliberate, explicit policy decision when retirement is actually exercised (not part of this infra task) — e.g. surfacing PortingTooOldError through the existing ActiveSessionRecoveryDialog/MultiSessionsRecoveryDialog recovery UX as a "this local draft is too old to recover, discard it" case, which those dialogs already support discarding through. Flagging this now so it isn't a surprise the first time a retirement actually happens; not solving it here since no retirement is being done in this task (only one version, minSupportedVersion = 0, ever exists so far).

1.1 Where schemas and porters live, and how they stay type-safe

Two things need answering concretely: (a) where do frozen historical schemas/types and porter functions physically live, and (b) how do we get TypeScript to actually check that porter N correctly hands version N's type at least the ports.

File layout — one versions/ subfolder next to whatever already holds the live schema (PrivateWorkbenchSession.schema.ts for the framework, a module's settings/persistence.ts for modules), created only once a version bump is actually needed (most modules will never have one):

frontend/src/framework/internal/WorkbenchSession/
  PrivateWorkbenchSession.schema.ts     # unchanged location: the LIVE (current-version) type + schema
  persistence/
    contentPorters.ts                    # composes the PorterChain for the whole content object
    versions/
      v0.ts                              # ContentV0 type + CONTENT_SCHEMA_V0 (frozen copy of the pre-this-change schema)
      v0ToV1.ts                          # portV0ToV1: ContentV0 -> SerializedWorkbenchSessionContentState

and, for a module that later needs a bump (none do yet — shown for e.g. Vfp settings as illustration):

frontend/src/modules/Vfp/settings/
  persistence.ts                         # unchanged: LIVE SerializedSettings type + SERIALIZED_SETTINGS_SCHEMA (via SchemaBuilder, as today)
  persistence.porters.ts                 # composes the settings PorterChain
  persistence.versions/
    v0.ts                                # SerializedSettingsV0 + frozen schema (via SchemaBuilder<SerializedSettingsV0>, same convention modules already use)
    v0ToV1.ts                            # port function

Frozen schemas are written with whichever style the surrounding code already uses — SchemaBuilder<T> (frontend/src/modules/_shared/jtd-schemas/SchemaBuilder.ts, used by every module today) for module version schemas, plain JTDSchemaType<T> object literals for the framework-content schema (matching PrivateWorkbenchSession.schema.ts's existing style). Both produce a plain JTDSchemaType<T>, which is all PortStep.schema requires — no new schema-authoring mechanism needed.

Type safety across the chain — a porter function is just a normal, named function declaration, e.g. function portV0ToV1(v0: ContentV0): SerializedWorkbenchSessionContentState { return {...}; }, so a wrong/missing field is caught the same way any TS function body is checked today (named function declarations throughout — no arrow-function consts — for stack-trace readability and consistency with the rest of this plan's examples). The harder part is making sure adjacent porters agree with each other and that the last porter's output actually matches the live current type. A small fluent builder in porting.ts, built on top of the PorterChain<TFinal> type already shown above, gets both for free from ordinary generic inference — no variadic-tuple trickery needed:

export class PorterChainBuilder<TCurrent> {
    private constructor(
        private readonly minSupportedVersion: number,
        private readonly steps: PortStep<any, any>[],
    ) {}

    // `minSupportedVersion` is the version of T0 — i.e. the oldest version this chain still
    // supports right now. It's 0 until/unless an older step has since been retired (see above).
    static start<T0>(minSupportedVersion: number): PorterChainBuilder<T0> {
        return new PorterChainBuilder<T0>(minSupportedVersion, []);
    }

    // `schema` must describe TCurrent (the type tracked so far) and `port` must consume
    // exactly that type — TS enforces both automatically via the class's own generic param.
    next<TNext>(schema: JTDSchemaType<TCurrent>, port: (data: TCurrent) => TNext): PorterChainBuilder<TNext> {
        return new PorterChainBuilder<TNext>(this.minSupportedVersion, [...this.steps, { schema, port }]);
    }

    build(currentSchema: JTDSchemaType<TCurrent>): PorterChain<TCurrent> {
        return {
            steps: this.steps,
            minSupportedVersion: this.minSupportedVersion,
            currentVersion: this.minSupportedVersion + this.steps.length,
            currentSchema,
        };
    }
}

Usage (contentPorters.ts):

export const CURRENT_WORKBENCH_SESSION_CONTENT_VERSION = 1;

export const WORKBENCH_SESSION_CONTENT_PORTER_CHAIN: PorterChain<SerializedWorkbenchSessionContentState> =
    PorterChainBuilder.start<ContentV0>(0)
        .next(CONTENT_SCHEMA_V0, portV0ToV1)
        .build(WORKBENCH_SESSION_CONTENT_STATE_SCHEMA);

export const CURRENT_WORKBENCH_SESSION_CONTENT_VERSION =
    WORKBENCH_SESSION_CONTENT_PORTER_CHAIN.currentVersion;

Because the exported constant is explicitly annotated PorterChain<SerializedWorkbenchSessionContentState>, TS checks that the builder's tracked type after the last .next() call and the supplied live schema both describe the declared current type. currentVersion is derived from minSupportedVersion + steps.length, so the version constant cannot drift independently from the chain. If a future .next() is appended with a porter whose output drifts from what the live type expects, or if the live type changes without updating the final porter and schema, this declaration fails to compile or the schema-integrity CI check fails — the chain's type-correctness and version consistency are enforced where framework/module code declares "this is what my current version looks like," with no separate manually maintained version number. When a future retirement happens (see 1.2), the only changes needed here are: delete the retired .next(...) call(s) for the pruned versions, delete their frozen schema/type/porter files, and bump the start<T{n}>(n) call to the new floor version and type.

1.2 How retirement decisions actually get made (and why this should eventually be automated, not eyeballed)

Retiring a porter (raising minSupportedVersion) is only safe once nobody can hand the chain data below that floor anymore. That has two independent preconditions, and getting either wrong silently breaks loading for real users:

1. Backend: the independent batch-porting service (future follow-up, out of scope here) must have completed a full, error-free pass confirming zero documents remain below the version being retired — not "probably none," an actual confirmed sweep, since any single unmigrated row would start throwing PortingTooOldError the moment its porter is deleted.
2. localStorage: even with (1) satisfied, a local draft that was never reopened since before the bump (section 2's write-back mitigates but doesn't eliminate this) could still be sitting below the floor. Retiring should therefore also wait out a deliberate grace period past whatever the app's realistic "longest a user goes without opening it" window is, not just the moment the backend sweep finishes.

A developer manually eyeballing "has the batch job finished, and has it been long enough" before deleting porter files is exactly the kind of judgment call that's easy to get wrong under time pressure (delete too early → real user sessions start failing to load with no warning until someone hits it in production). This plan does not build that guardrail now — the batch-porting service itself is a separate follow-up — but the design should leave an obvious hook for it: when that service exists, it should be the single source of truth for precondition (1), e.g. by emitting a small checked-in or fetchable manifest per versioned schema (framework content, and eventually per module) recording the last version it has confirmed fully migrated and when. A future CI check or lint rule could then simply refuse a minSupportedVersion bump in contentPorters.ts (or a module's persistence.porters.ts) unless the manifest confirms that version has been clear for at least as long as the chosen grace period — turning "did someone remember to check" into an enforced, automatic gate rather than a manual step someone has to remember. Noting this now so the eventual batch-service design bakes in producing that manifest from day one, rather than bolting it on after the first retirement mistake.

2. Framework content versioning (eager, at session load)

• Add version: number to SerializedWorkbenchSessionContentState (frontend/src/framework/internal/WorkbenchSession/PrivateWorkbenchSession.schema.ts) and its JTD schema. The schema always describes only the current shape. Data below the current version is never handed to this schema directly — it's validated hop-by-hop against each version's own frozen schema inside portToLatest (section 1) first, and only reaches this current-version schema once fully ported.

• PrivateWorkbenchSession.ts: serializeContentState() (~L198) emits version: CURRENT_WORKBENCH_SESSION_CONTENT_VERSION. The three ad-hoc-optional fields (~L30-44) become required again, and their "awaiting schema versioning" comments are removed — this is the concrete migration this system unlocks.

• Following the layout in 1.1: persistence/versions/v0.ts exports ContentV0 (today's shape, frozen: three fields still optional, no version) and CONTENT_SCHEMA_V0: JTDSchemaType<ContentV0> (a literal copy of today's WORKBENCH_SESSION_CONTENT_STATE_SCHEMA, taken before this change is made so it stays byte-for-byte what old data actually looked like). persistence/versions/v0ToV1.ts exports portV0ToV1(v0: ContentV0): SerializedWorkbenchSessionContentState, backfilling the three fields (default "") and stamping version: 1. persistence/contentPorters.ts composes these via PorterChainBuilder into WORKBENCH_SESSION_CONTENT_PORTER_CHAIN: PorterChain<SerializedWorkbenchSessionContentState>, exports CURRENT_WORKBENCH_SESSION_CONTENT_VERSION = 1, and getStoredContentVersion(raw): number (treats content with no version field as version 0).

• Wire into frontend/src/framework/internal/WorkbenchSession/utils/deserialization.ts: in all three loaders (deserializeFromLocalStorage, deserializeSessionFromBackend, deserializeSnapshotFromBackend), insert portToLatest(...) between JSON.parse and the existing validateContent/validateFull AJV calls. Each hop inside portToLatest validates the data against that hop's own frozen schema before porting it forward (section 1); the existing validateContent/validateFull calls afterward then validate the final, fully-ported result against the current schema exactly as they do today. This two-tier validation is required because JTD schemas are closed/strict: an old, unversioned shape must never be validated against the current schema directly, but it must also never be handed to a porter function unchecked.

• Local storage gets silently upgraded on load, not just in memory. It would be tempting to assume the existing autosave pipeline (SessionStateTracker/LocalBackupManager, PERSISTENCE_ARCHITECTURE.md "Change Detection & Auto-Save") already re-persists the now-ported content automatically — but checking SessionStateTracker.initialize() (frontend/src/framework/internal/persistence/core/SessionStateTracker.ts ~L54-101) shows it deliberately seeds currentHash = lastPersistedHash = backendHash for any session that has a backend hash, specifically "to prevent false positives from deserialization artifacts." That means for any session that's ever been synced to the backend (the common case), porting during load would NOT be picked up as a change by the normal autosave/hash-diff path, and the upgraded content would stay purely in memory until the user's next real edit or explicit save — leaving the on-disk localStorage copy stuck at its old version indefinitely if the user never edits before closing the tab.

  To make the upgrade durable, add an explicit (not hash-diff-dependent) write-back: in frontend/src/framework/internal/WorkbenchSession/utils/loaders.ts (loadWorkbenchSessionFromLocalStorage, loadAllWorkbenchSessionsFromLocalStorage) and in WorkbenchSessionManager's backend-open path, after porting produces a content.version that differs from getStoredContentVersion(raw) (i.e. porting actually did something), immediately re-write the corresponding localStorage entry with the now-current-version content, using the same helpers LocalBackupManager already uses to persist (makeWorkbenchSessionLocalStorageString/the existing local storage key format in localStorageHelpers.ts) — a plain, synchronous localStorage.setItem, independent of SessionStateTracker's dedupe logic (which exists to suppress noise from user-edit detection, not to gate this one-time, on-load version migration). Skip the write when storedVersion === currentVersion to avoid needless writes on the (eventual) steady-state common path.

  This narrows, but doesn't eliminate, the localStorage caveat above: any local session that gets opened even once between two version bumps is durably upgraded to current on that open, so only sessions that are never reopened at all across a whole version bump remain at risk of eventually hitting PortingTooOldError after a retirement. That's a meaningfully smaller and more defensible risk surface than "every stale local draft, forever."

3. Module state versioning (lazy, per module instance)

• Wrap each module's stringified settings/view in an envelope outside of what AJV validates: { format: "webviz-module-state", version: number, data: TSerializedState }. The fixed format discriminant prevents a legacy payload that already happens to contain version and data properties from being misidentified as an envelope. AJV schemas keep validating only data's inner shape, exactly as today, and ModuleInstance.schema.ts/PrivateWorkbenchSession.schema.ts still see serializedState.settings/.view as opaque strings.
• New file frontend/src/framework/ModulePersistence.ts (no React/jotai imports): VersionedEnvelope<T>, ModuleComponentPersistence<T> = { settings?: PorterChain; view?: PorterChain }, wrapInEnvelope, and unwrapLegacyOrEnvelope(raw): { version, data }. Only objects with the exact envelope discriminant are treated as envelopes; all other payloads are legacy version 0 data.
• Every persisted module settings/view schema must register a stable persistence ID and a version-0 chain from the moment it participates in persistence, even when it has no migration steps yet. This creates a fingerprintable baseline and prevents version 0 from silently changing shape before the first porter is introduced. No module needs a version bump today, so no module gets historical porter files as part of this task; existing modules register empty chains whose currentSchema is their live schema. The first time a module shape changes, its author promotes the registered v0 snapshot, writes v0ToV1.ts, adds golden fixtures, and extends the same chain.
• frontend/src/framework/internal/ModuleInstanceSerializer.ts:
  • getStringifiedSerializedState() (~L94) wraps each component in its discriminated envelope before JSON.stringify, using the component's registered chain version. A persisted component always has a registered baseline; an empty chain therefore means a stable, fingerprinted version 0, not "untracked."
  • deserializeState(raw) (~L172): after JSON.parse, call unwrapLegacyOrEnvelope then portToLatest(data, version, chain) (chain optional — skip if module never registered one) before the existing per-component AJV validation.
  • Constructor gains a porterChains: ModuleComponentPorterChains<TSerializedState> param (default {}), stored alongside the existing schema/serialization-function fields.
• Author ergonomics — mirror the existing setSerializationFunctions pattern module authors already know from PERSISTENCE_ARCHITECTURE.md:
  • Module.tsx: new setPortingFunctions(chains) / getPortingFunctions(), sibling to setSerializationFunctions/getComponentSerializationFunctions (~L286-292). Additive only — default {}.
  • ModuleInstance.ts: makeSerializer (~L250) already calls this._module.getSerializedStateSchema() internally — extend it to also call this._module.getPortingFunctions() and pass both through to new ModuleInstanceSerializer(...). No signature change needed at the one call site (Module.tsx:344, instance.makeSerializer(this._serializationFunctions)).
  • ModuleRegistry.ts: add optional portingFunctions?: ModuleComponentPorterChains<TSerializedStateDef> to InitModuleOptions (~L38-50), and in initModule (~L96-126) call module.setPortingFunctions(options.portingFunctions) when present — same shape as the existing serializeStateFunctions/deserializeStateFunctions handling. Once a module does need a version bump, its author passes portingFunctions: { settings: settingsPorterChain } (built as in 1.1/3 above) into loadModule.tsx's ModuleRegistry.initModule(...) call, next to serializeStateFunctions. Modules that never do this are unaffected — legacy/unenveloped blobs pass straight through exactly as they do today.

4. Why this satisfies the "reusable in an independent service" requirement

Every porting-related file introduced (porting.ts, contentPorters.ts, and any future module persistence.porters.ts) has zero React/jotai/DOM imports — only plain data in, data out, plus type-only imports of the current schema types (erased at runtime, just used for compile-time drift-checking). A future standalone Node script can import these exact files directly without pulling in registerModule.tsx/loadModule.tsx (React-heavy) or any browser runtime, giving a single source of truth for migration logic shared between the live app and a batch job.

5. Human-error mitigation, merge protection, and change ownership

The migration runner protects data at runtime, but runtime validation alone is too late for the most likely failure: a developer changes a persisted schema without realizing that they changed a long-lived storage contract. Persistence artifacts therefore follow an append-only workflow enforced by tooling, CI, repository ownership, and explicit exception procedures.

5.1 Protected artifacts and invariants

Each persistence domain (for example workbench-session-content or modules.vfp.settings) has a stable ID and a generated manifest entry containing:

• currentVersion and a canonical hash of currentSchema;
• minSupportedVersion;
• a canonical hash for every frozen historical schema;
• a source hash for every shipped porter;
• hashes for golden migration fixtures;
• optional retirement authorization metadata.

Schemas are canonicalized before hashing, so formatting, comments, and object-property order do not create false changes. Historical schemas must be self-contained static data: only type-only imports, Ajv/JTD types, and files inside the same immutable version directory are allowed. Importing a mutable shared live schema into a historical version is rejected by lint/CI because it would make that historical schema change transitively.

The following invariants are blocking merge conditions:

1. A current schema hash may not change unless the domain's version increases by exactly one and a complete migration package is added.
2. currentVersion is derived from the chain and cannot be maintained separately.
3. Existing frozen schemas, shipped porters, and accepted golden outputs are immutable in ordinary PRs.
4. A version bump requires: the promoted previous-current schema, a new porter, at least one representative before/after fixture, chain registration, and successful contract tests.
5. Every persisted module component is registered from version 0; there is no untracked persisted schema.
6. minSupportedVersion may not increase through the ordinary schema-change workflow. Retirement has its own authorization gate.

5.2 Common failure scenarios and mitigations

Scenario	What could happen	Prevention before merge	Runtime/backstop
Developer adds/removes/changes a persisted field but forgets a version bump	Old documents claim the current version but fail to load	CI detects a changed canonical current-schema hash with unchanged version/chain and blocks the PR	Current-schema validation produces a clear PortingValidationError rather than accepting malformed data
Developer edits a frozen schema to "fix" it	Documents of the same claimed historical version are interpreted differently across releases	Integrity manifest hash changes; protected-history CI job blocks the PR	Historical fixtures continue to expose incompatibility, but merge protection is the primary control
A shared schema fragment used by a frozen schema changes	Frozen schema changes transitively even though its file was untouched	Historical directories may not import mutable runtime schema fragments; dependency/lint check blocks it	Manifest generation evaluates and hashes the effective schema
Developer edits an already-shipped porter	Identical old documents may migrate to different current data depending on app version	Porter source hash is immutable; ordinary PR is blocked	A corrective new version is preferred; emergency override requires explicit approval and impact analysis
Porter is type-correct but maps fields incorrectly	Migration succeeds structurally but corrupts meaning	Required golden before/after fixtures and reviewer-visible migration diff	Output is validated at each boundary; representative production fixtures should be added when available
Porter mutates its input	Retry, logging, or parallel processing can observe partially migrated data	Generic contract test deep-freezes/clones input and asserts no mutation	Pure-function convention and standalone batch execution remain safe
Version constant and chain length drift	Missing steps or unreachable versions	Version is derived by build(currentSchema); CI checks continuity	Runner still throws on missing steps
Module introduces an envelope whose shape collides with legacy data	Valid legacy payload is misread as metadata	Exact format: "webviz-module-state" discriminant and collision tests	Non-matching values are treated as legacy v0 data
Module schema changes before its first porter is registered	Both old and new shapes are labelled v0	Every persisted component must register and fingerprint its v0 schema immediately	Current-schema validation catches affected data, but CI prevents the merge
Developer removes an old porter after the backend batch job	Stale localStorage drafts become unloadable	Retirement CI requires backend sweep evidence, grace-period expiry, and recovery UX readiness	PortingTooOldError is surfaced through recovery/discard UI
Two branches independently bump the same schema version	Merge can create two incompatible vN -> vN+1 histories	Manifest/chain conflict is intentionally non-auto-resolvable; rebased branch must create the next version	Full-chain tests verify continuity after rebase

5.3 CI protection

Add a dedicated required status check named Persistence schema compatibility. It runs independently of the general unit-test job so a persistence-contract failure is visible and cannot be dismissed as an unrelated test failure. It performs:

1. Manifest regeneration and integrity comparison

   • Regenerate canonical hashes for current schemas, historical schemas, porters, and fixtures.
   • Fail if any existing historical artifact changed.
   • Fail if a current schema changed without a complete one-step version bump.
   • Fail on orphaned version files, duplicate persistence IDs, missing registrations, or chain gaps.

2. Import and static-data restrictions

   • Reject runtime imports from historical version directories except explicitly frozen same-version files.
   • Reject React/jotai/DOM imports from all porter and schema-manifest code.
   • Reject non-static schema construction that depends on mutable defaults or application state.

3. Generic migration contract suite

   • Validate each fixture against its claimed input schema.
   • Assert the porter is deterministic and does not mutate input.
   • Validate each hop and the final output.
   • Assert the output version and golden output.
   • Run every supported historical fixture through the full chain to current.

4. PR migration report

   • Publish a concise PR summary showing persistence IDs changed, version transitions, schema diff, added/removed required fields, new fixtures, historical modifications, and any minSupportedVersion change.
   • Any historical modification or retirement is highlighted as a privileged operation.

5. Merge-base protection

   • The bump tool promotes the previously committed current-schema snapshot from the merge base/manifest, not the developer's already-edited working-tree schema. This prevents accidentally freezing the new schema as the old version.

The preferred authoring command is a repository script such as:

npm run persistence:bump -- workbench-session-content

It promotes the recorded current schema, creates the next porter and fixture skeletons, and updates the manifest. Hand-creating or renaming version directories is allowed only when the generated result is equivalent and all CI checks pass, but the generated workflow is the supported path.

5.4 Who can change what, and when

Repository CODEOWNERS should require approval from the persistence/framework owners for:

• shared porting infrastructure and manifest generation;
• live framework persistence schemas;
• any persistence.porters.ts, historical schema, porter, fixture, or minSupportedVersion change;
• module persistence registration APIs and envelope format.

Module owners may change their module's live serialization code and propose module schema migrations, but a persistence/framework owner must approve any persisted-schema hash change. The ownership model is:

Change	Who may author	Required approval	When it is allowed
Change non-persisted application code	Any relevant developer	Normal code owners	Ordinary PR
Change serialization implementation without changing the canonical schema	Module/framework developer	Normal code owners; persistence CI must confirm no schema change	Ordinary PR
Add a new persisted component at version 0	Module owner	Module owner + persistence/framework owner	Before the component writes production data
Bump a live schema and add a new porter	Module/framework owner	Module owner + persistence/framework owner	Ordinary feature PR with complete migration package
Add fixtures for an existing migration without changing accepted output	Any developer	Persistence/framework owner	Ordinary corrective/test PR
Modify an existing frozen schema, shipped porter, or accepted golden output	Not allowed in ordinary workflow	Persistence/framework owner plus designated technical lead; explicit emergency CI override	Only after documented impact analysis; normally create a corrective next version instead
Increase minSupportedVersion or delete historical artifacts	Batch-migration/operations owner	Persistence/framework owner + technical lead/product service owner	Only after verified zero-old-row backend sweep, grace-period expiry for localStorage, and recovery UX availability
Change the envelope discriminant or stable persistence ID	Not an ordinary refactor	Persistence/framework owner + technical lead	Only as an explicitly migrated format change

Protected branches must require the persistence compatibility check and required CODEOWNER approvals; administrators should not routinely bypass them. Emergency overrides must be auditable in the PR and include: reason, affected domains/versions, expected production impact, recovery plan, and whether a corrective new migration was considered.

5.5 Retirement authorization

Raising minSupportedVersion is administratively separate from adding a migration. A checked-in retirement record must identify the persistence domain, new floor, completed backend sweep/job ID and timestamp, localStorage grace-period deadline, approving owners, and confirmation that PortingTooOldError has a supported recovery path. CI rejects the floor increase until all conditions are satisfied. Because localStorage cannot be exhaustively inventoried, retirement remains a conscious product decision rather than a purely technical cleanup.

Critical files

• frontend/src/framework/utils/persistence/porting.ts (new) — shared chain-port runner
• frontend/src/framework/internal/WorkbenchSession/PrivateWorkbenchSession.schema.ts — add version field/schema
• frontend/src/framework/internal/WorkbenchSession/PrivateWorkbenchSession.ts — emit version, un-optionalize the 3 fields
• frontend/src/framework/internal/WorkbenchSession/persistence/contentPorters.ts + persistence/versions/v0.ts + persistence/versions/v0ToV1.ts (new) — the v0→v1 framework porter and its frozen schema
• frontend/src/framework/internal/WorkbenchSession/utils/deserialization.ts — port before validate, all 3 loaders
• frontend/src/framework/internal/WorkbenchSession/utils/loaders.ts (and the relevant WorkbenchSessionManager.ts open path) — explicit write-back of upgraded content to localStorage on load
• frontend/src/framework/ModulePersistence.ts (new) — envelope + module porter-chain types
• frontend/src/framework/internal/ModuleInstanceSerializer.ts — envelope wrap/unwrap + porting hook
• frontend/src/framework/Module.tsx — setPortingFunctions/getPortingFunctions
• frontend/src/framework/ModuleInstance.ts — thread porting functions through makeSerializer
• frontend/src/framework/ModuleRegistry.ts — portingFunctions option on InitModuleOptions
• No permanent module porter files are added by this task (see section 3) — the Vfp module is used only transiently in manual verification (below) to smoke-test the wiring end to end, then reverted.

Verification

1. Unit tests (new, alongside existing frontend/tests/unit/framework/** conventions):
   • porting.test.ts: no-op when stored === current version; multi-hop chaining; throws on stored > current; throws on a missing porter mid-chain; throws PortingValidationError (not a raw crash) when data claiming version v doesn't actually match version v's frozen schema (e.g. a corrupted/hand-edited fixture), confirming the fix from this design pass — the porter function itself is never reached with malformed input; a chain built with minSupportedVersion > 0 (simulating a retired-steps scenario) correctly offsets into steps and still starts porting at the right hop; storedVersion < minSupportedVersion throws PortingTooOldError.
   • contentPorters.test.ts: a hand-built legacy (no version, missing case-name fields) fixture passes CONTENT_SCHEMA_V0 validation, ports to v1, and then passes validateContent.
   • deserialization.test.ts: feed a v0 JSON string through all three loaders, assert content.version === CURRENT_WORKBENCH_SESSION_CONTENT_VERSION and the backfilled fields are present.
   • ModuleInstanceSerializer.test.ts: a fake one-hop settings porter chain — legacy unenveloped string gets ported; an already-current discriminated envelope skips porting; a legacy payload containing ordinary version and data fields is not mistaken for an envelope.
   • Generic migration-contract tests: every registered domain's fixtures validate against their claimed input schema, port deterministically without input mutation, match golden output, and validate against the final current schema.
   • Manifest/CI tests: current-schema changes without a version bump fail; historical schema/porter changes fail; mutable imports from frozen directories fail; duplicate IDs, chain gaps, and unauthorized minSupportedVersion increases fail.
2. Manual check: capture a real pre-change localStorage session value, seed it back in after the change, reload the dev app, and confirm it loads cleanly with backfilled case names instead of undefined. Then save a fresh session and confirm it round-trips with version stamped. Also confirm the write-back: after the reload, inspect the raw localStorage entry directly (devtools) without making any edits, and verify it has already been rewritten to version: 1 with backfilled fields — proving the upgrade is durable on disk, not just in memory.
3. Run npm run test (or the project's unit test command), typecheck (tsc --noEmit or the existing lint/typecheck script), and the new Persistence schema compatibility job to confirm no regressions in the 5+ modules that already declare serializedStateSchema.
4. Merge-protection smoke test: in a temporary branch, verify that changing a live schema without bumping fails CI; changing one byte of a frozen schema or existing porter fails CI; and using the supported bump command produces a PR report with the expected version transition and schema diff.

[SNIP]

5. Migration outcomes and user communication

A migration is not simply "successful" or "failed". While many schema changes can be migrated losslessly, others inherently require approximation or discarding information because older persisted data lacks concepts introduced in later versions, or because a module has fundamentally changed its internal model.

The migration infrastructure therefore distinguishes between technical correctness (the ability to produce a valid document conforming to the current schema) and semantic completeness (whether the migrated document fully represents the intent of the original).

5.1 Migration outcomes

Every migration step falls into one of three categories.

Lossless migration

The porter is able to construct a semantically equivalent document in the newer version.

Examples include renaming fields, splitting or merging fields, changing serialization formats, and internal structural refactoring. No user notification is required.

Best-effort migration

The porter can produce a valid current-version document, but some information cannot be reconstructed because it never existed in the historical representation or because no reliable mapping exists.

Examples include newly introduced required fields receiving default values, removal of obsolete features, fundamental redesign of a module, resetting view state because the previous representation no longer exists, or replacing unsupported settings with reasonable defaults.

The migrated document remains usable, but the user should be informed that some information was approximated, defaulted or discarded.

Migration failure

If no meaningful current representation can be produced without risking misleading behaviour, the porter shall fail and the affected component should enter the existing recovery flow.

5.2 Structured migration issues

Porters may emit structured migration issues describing information that could not be preserved exactly.

export type MigrationIssueSeverity = "info" | "warning" | "error";

export interface MigrationIssue {
    severity: MigrationIssueSeverity;
    code: string;
    component?: string;
    path?: string;
    details?: unknown;
}

Issues are accumulated across the migration chain. Porters expose stable issue codes only; the frontend is responsible for localization and presentation.

5.3 User communication

Users care about the impact of a migration, not schema versions.

Notifications should therefore explain:

• what was affected,
• what could not be restored,
• which fallback was used,
• what the user should verify.

Migration issues should be aggregated into a single notification rather than producing multiple dialogs.

5.4 Best-effort must never hide corruption

Best-effort migration only applies to valid historical documents whose schemas legitimately lack information required by newer versions.

Malformed or corrupted data must fail validation before any porter executes.

5.5 Preserving original data

Potentially lossy migrations should avoid immediately destroying the only remaining copy of the original document. Local storage implementations may temporarily preserve the original serialized representation until the migrated document has been successfully loaded and persisted.

5.6 Migration quality classification

Each migration step should explicitly declare whether information loss is expected.

type MigrationQuality = "lossless" | "potentially-lossy";

For potentially-lossy migrations, CI should require golden migration fixtures, documented fallback behaviour, expected migration issues and explicit persistence-owner review.