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):
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:
| Location | Newer version encountered | Unmigrated older version |
|---|---|---|
| Device outbox | Opens refused (UnsupportedMessageVersionError) | Moved to status.refused; rest sends |
| Server append | Exchange fails before commit; client waits | Rejected as Unreadable { version } |
| Journal history | UnreadableHistoryError on reads before it | Same |
| Committed tail to replica | Exchanges fail until page reloads | InvalidReplicaHistoryError 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.