Skip to content

Generated file. Source: docs/data_persistence_contracts.md Edit the source document and run npm run docs:sync to refresh this published copy.

Data and Persistence Contracts

Purpose

This document defines the future-facing persistence boundary for:

  • saved simulations
  • prediction history
  • later portfolio-oriented features

It complements the canonical result model contract.

The key rule is simple:

  • the canonical result model is the stable runtime output of the engine
  • persistence contracts define what must be stored, versioned, and reconstructed later

Why This Matters

Roadmap stages 2 and 3 require more than transient UI state.

The project will need to preserve:

  • the input state used for a simulation
  • the exact result snapshot shown to the user
  • optional prediction metadata used at calculation time
  • later, portfolio-oriented history and comparison with reality

Without an explicit contract, storage risks coupling itself to current UI state, temporary store shape, or view-only assumptions.

Contract Layers

1. Canonical runtime result

Defined in result_model_contract.md.

Role:

  • engine output
  • UI input
  • export input
  • basis for persistence snapshots

2. Persistence snapshot

Role:

  • durable representation of a completed simulation
  • suitable for saved simulations, history, and future reload

Current reference TypeScript shape:

  • SavedSimulationRecord
  • SavedSimulationDraft
  • InflationPredictionSnapshot
  • PortfolioSnapshot
  • SavedSimulationRepository
  • SavedSimulationService

Source:

  • src/app/domain/persistence/types.ts
  • explicit portfolio contract:
  • src/app/domain/portfolio/types.ts
  • explicit prediction-history contract:
  • src/app/domain/prediction-history/types.ts
  • runtime repository:
  • src/app/domain/persistence/repository.ts
  • runtime service:
  • src/app/domain/persistence/service.ts
  • prediction-history runtime repository/service:
  • src/app/domain/prediction-history/repository.ts
  • src/app/domain/prediction-history/service.ts

Runtime Ownership

The current runtime flow is intentionally split into three layers:

  • store history
  • short-lived session history for the current calculator experience
  • SavedSimulationService
  • durable application-level workflow for saved simulations
  • SavedSimulationRepository
  • storage adapter that persists records
  • PredictionHistoryService
  • durable workflow for prediction metadata and linked forecast records
  • PredictionHistoryRepository
  • storage adapter that persists prediction history records

This means saved simulations are no longer modeled as a side effect of the session-history list.

The design goal is:

  • session history can stay lightweight and UI-oriented
  • saved simulations stay durable, versioned, and reconstructable

Minimum Saved Simulation Contract

Every saved simulation should preserve:

  • schema version
  • stable record identifier
  • save timestamp
  • optional human label
  • normalized investment parameters
  • canonical result snapshots
  • compact summary for listing and quick ranking
  • optional prediction snapshot metadata
  • optional portfolio snapshot when portfolio workflows arrive
  • portfolio snapshot shape is now defined explicitly in the dedicated portfolio-domain module

This is intentionally more stable than current UI state.

It should not depend on:

  • active tab selection
  • visible columns
  • chart mode
  • local presentation toggles

Inflation Prediction Snapshot

Stage 3 should not only compute predictions.

It should also preserve the metadata that explains what prediction was used:

  • source
  • capture time
  • assumed inflation
  • forecast horizon
  • optional notes

That enables:

  • later comparison with reality
  • historical reproducibility
  • auditability of forecast-backed outputs

The current runtime direction now supports:

  • saving prediction snapshots through a dedicated prediction-history service
  • linking a saved simulation to a prediction-history record through an identifier
  • keeping prediction metadata out of transient UI state

What Does Not Belong Here

The persistence contract should not directly store:

  • ephemeral UI toggles
  • tooltip state
  • layout mode
  • component-local sorting or filtering choices

Those belong to presentation state, not durable simulation history.

Relationship to the Roadmap

Stage 2

Needs explicit saved simulation contracts and a repository/service/runtime boundary that owns them.

Stage 3

Extends the persistence boundary with prediction metadata and later comparison context.

Stage 6

Will likely require richer account and contribution history contracts.

Stage 7

Assistant-led flows will benefit from being able to reconstruct full simulations from saved domain-level snapshots rather than UI state.

Design Rule

Persistence should depend on:

  • normalized input parameters
  • canonical result model
  • explicit prediction metadata
  • repository/service boundaries that can be tested independently from UI state

It should not depend on:

  • transient view models
  • component-specific representations
  • ad hoc store serialization