Persistence and Deploys

Persistence in Vango is deliberate, not automatic.

What persists

Persisted app state is:

• setup.SharedSignal

• setup.GlobalSignal

• vango.SessionKey[T]

Not persisted:

• setup.Signal

• setup.Memo

• setup.Resource

• setup.Action

• props

• effect lifecycle

• request or session scratch data

Persist durable UX state intentionally. Do not persist everything just because the framework supports persistence.

Persisted initializers must be deterministic

Allowed initializers are limited to literals, constant expressions, and simple deterministic construction.

Do not use:

• props

• environment values

• time

• random IDs

• I/O

• helper calls that depend on runtime context

If the initializer needs runtime context, it is almost certainly the wrong persisted shape.

Schema IDs

If a persisted type should survive refactors such as package moves or renames, give it a stable schema ID.

go

1func (UserPrefs) VangoSchemaID() string {
2	return "myapp:UserPrefs:v1"
3}

Changing the schema ID is a compatibility change. Do it deliberately.

Warm vs cold deploy

Warm deploy:

• persisted schema stays compatible

• sessions resume normally

Cold deploy:

• persisted schema breaks compatibility

• sessions refresh instead of resuming

Typical warm changes:

• adding new persisted state

• safe refactors where tooling preserves continuity

Typical cold changes:

• removing persisted state

• incompatible persisted type changes

• schema ID changes

Review the generated plan and artifacts literally instead of guessing.

Generated artifacts

Commit these files:

• vango_state_manifest.json

• vango_state_schema.json

• generated vango_state_bindings_gen.go files

You do not hand-edit them. You review them and commit them alongside the source change.

Persistence errors and budgets

Persisted writes can fail because of:

• per-value budget limits

• per-session budget limits

• storage errors

• codec errors

Use s.OnPersistError(...) when you want app-level UI handling.

If you hit persistence budgets routinely, redesign the state shape instead of just increasing limits.

Practical checklist

• persist only small durable UX state

• persist references instead of large blobs

• keep initializers deterministic

• add stable schema IDs to types that need refactor safety

• review warm versus cold impact on every persisted-state change

• commit generated artifacts with source changes

Continue to Security and Operations for the deployment and runtime side of the framework.