Sync / Replicated state

Changing a durable Message

Durable Messages sit in offline outboxes and server logs across releases, so editing an existing Message schema breaks old entries. Declare versioned migrations with migrations(...) instead (for example, renaming text to title):

ts
import { Match } from 'effect'
import { migrations } from 'foldkit-sync'

const RenamedTodoV1 = Schema.TaggedStruct('RenamedTodo', {
  id: Schema.String,
  text: Schema.String,
})
const MessageV1 = Schema.Union([Message.CreatedTodo, RenamedTodoV1])

const TodoHistory = migrations(MessageV1).next(App.Message, previous =>
  Match.valueTags(previous, {
    CreatedTodo: created => created,
    RenamedTodo: ({ id, text }) => ({ _tag: 'RenamedTodo' as const, id, title: text }),
  }),
)

const VersionedTodos = forApplication(App).make({
  documentId: DocumentId.make('todos'),
  shared: Projection.pick(App.model.todos),
  durable: MessageSet.make(App, [Message.CreatedTodo, Message.RenamedTodo]),
  migrations: TodoHistory,
})

Never edit shipped migration steps—append another .next(...) instead. Each operation records its original messageVersion, while update, authorize, validate, stamp, and reduce always receive the upcast current Message. The journal checks retransmissions against the original wire bytes so retries across deploys still match.

What happens when an actor meets an unknown or unreadable version:

LocationNewer version encounteredUnmigrated older version
Device outboxOpens refused (UnsupportedMessageVersionError)Moved to status.refused; rest sends
Server appendExchange fails before commit; client waitsRejected as Unreadable { version }
Journal historyUnreadableHistoryError on reads before itSame
Committed tail to replicaExchanges fail until page reloadsInvalidReplicaHistoryError on skew

Deploy in order: first ship the Sync version supporting messageVersion, then deploy your new application version to the server before clients. Migration steps must stay pure and deterministic. Note that migrations covers durable Messages; evolving the shared slice schema separately requires migrating stored snapshots.