State.MigrationFailure
luastra/stateState.MigrationFailure represents the unsuccessful branch of a bounded operation. Its stable code and structured context support control flow and safe diagnostics without parsing an exception message.
Before you use it
Add luastra/state to this module's dependencies in luastra.json, then import it with require("luastra/state"). No capability is required for encoding, decoding, or migration. Persistence additionally needs luastra/host plus storage.get and storage.set.
How it fits
The type describes string fields, migration functions, or tagged decode/migration results.
When to use it
Use State.MigrationFailure on the unsuccessful branch of the related result. Read its stable fields for control flow or diagnostics; do not parse human-readable assertion or error text.
Fields or definition
| Parameter | Type / values | Description |
|---|---|---|
| success | false | Discriminator that must be checked before reading branch-specific fields. |
| version | nil | Explicit contract version used to validate or migrate the serialized value. |
| fields | nil | Validated bounded field map carried by the decoded or migrated value. |
| encoded | nil | Deterministic snapshot string produced after a successful migration. |
| error | MigrationError | Bounded failure information, or nil on the successful branch. |
Error codes
This is the complete closed vocabulary emitted by the named operation in this Source SDK contract.
| Code | When it occurs |
|---|---|
| empty | The encoded source state is empty or not a string. |
| too_large | The encoded source state exceeds 4096 bytes. |
| invalid_target_version | targetVersion is not an integer from 1 through 999. |
| invalid_migrations | The migration collection is not a table. |
| malformed | The source version prefix is missing or invalid. |
| newer_version | The source version is newer than the requested target. |
| too_many_migrations | The migration would require more than 32 steps. |
| missing_migration | No migration function exists for the current version. |
| migration_failed | A migration function raised an error. |
| invalid_migration | A migration returned, encoded, or verified an invalid replacement. |
SDK type flow
Produced by
What happens next
A checked snapshot or result annotation.
Failures and fixes
Malformed data, wrong versions, missing migration steps, excessive size, or non-string fields remain explicit failure branches. Do not silently replace corrupt security- or domain-sensitive values with defaults.
Availability
Public-source alpha API in 0.5.0-alpha; persistence support is host-dependent.
Exact declaration
export type MigrationFailure = { success: false, version: nil, fields: nil, encoded: nil, error: MigrationError }