Skip to content

Fix durable state schema migration #228

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bigboateng merged 2 commits into from
Aug 17, 2026
Merged

Fix durable state schema migration #228

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ea41d50
Fix durable state schema migration
bigboateng Aug 17, 2026
beb67c2
Document durable state migration fix
bigboateng Aug 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions boatstack/internal/softwaredelivery/durable/state.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ import (

const (
StateSchemaVersion = 7
priorStateSchemaVersion = 4
priorStateSchemaVersion = 6
)

// CanReadStateSchema reports the current schema and its single supported
Expand Down Expand Up @@ -252,7 +252,7 @@ func DecodeState(value []byte) (State, error) {
return State{}, fmt.Errorf("durable state contains trailing JSON")
}
if state.SchemaVersion == priorStateSchemaVersion {
if state.PlanningPackageFingerprint != "" || state.ControlBundleFingerprint != "" || state.ProgramHumanIdentityRole != "" {
if state.ProgramHumanIdentityRole != "" {
return State{}, fmt.Errorf("durable state schema %d contains later identity fields", priorStateSchemaVersion)
}
state.SchemaVersion = StateSchemaVersion
Expand Down
10 changes: 5 additions & 5 deletions boatstack/internal/softwaredelivery/durable/state_schema_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ func TestStateSchemaPermitsLegacyApprovedStateWithoutApprovalFingerprint(t *test
}
}

func TestDecodeStatePromotesReleasedSchemaFourWithoutChangingPriorBytes(t *testing.T) {
func TestDecodeStatePromotesExactBaseSchemaWithoutChangingPriorBytes(t *testing.T) {
state := State{
SchemaVersion: StateSchemaVersion, RepositoryID: "repo", GitCommonID: "common", WorktreeID: "worktree", Revision: 7,
Phase: model.PhaseActive, Engagement: model.EngagementActive, Delivery: model.DeliveryApproved, Workspace: model.WorkspaceAbsent,
Expand All @@ -54,7 +54,7 @@ func TestDecodeStatePromotesReleasedSchemaFourWithoutChangingPriorBytes(t *testi
t.Fatal(err)
}
legacy["schema_version"] = float64(priorStateSchemaVersion)
delete(legacy, "control_bundle_fingerprint")
delete(legacy, "program_human_identity_role")
prior, err := json.MarshalIndent(legacy, "", " ")
if err != nil {
t.Fatal(err)
Expand All @@ -73,10 +73,10 @@ func TestDecodeStatePromotesReleasedSchemaFourWithoutChangingPriorBytes(t *testi
}
}

func TestDecodeStateRejectsSchemaFourWithLaterIdentityFields(t *testing.T) {
raw := []byte(`{"schema_version":4,"repository_id":"repo","git_common_id":"common","worktree_id":"worktree","program_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","planning_package_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","control_bundle_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","revision":1,"phase":"ACTIVE","engagement":"active","delivery":"approved","workspace":"absent","plan":"approved","configuration":"unsupported","runtime":"absent","publication":"none","verification":"unverified","recovery":"none","transaction":"none","terminal":"nonterminal","objective":{},"updated_at":"1970-01-01T00:00:01Z"}`)
func TestDecodeStateRejectsBaseSchemaWithNewHumanIdentityRole(t *testing.T) {
raw := []byte(`{"schema_version":6,"repository_id":"repo","git_common_id":"common","worktree_id":"worktree","program_fingerprint":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","program_human_identity_role":"developer","planning_package_fingerprint":"cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc","control_bundle_fingerprint":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","revision":1,"phase":"ACTIVE","engagement":"active","delivery":"approved","workspace":"absent","plan":"approved","configuration":"unsupported","runtime":"absent","publication":"none","verification":"unverified","recovery":"none","transaction":"none","terminal":"nonterminal","objective":{},"updated_at":"1970-01-01T00:00:01Z"}`)
if _, err := DecodeState(raw); err == nil {
t.Fatal("schema-4 state smuggled later identity fields")
t.Fatal("base schema state smuggled the new human identity role")
}
}

Expand Down
9 changes: 4 additions & 5 deletions boatstack/internal/softwaredelivery/effects/integration_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -814,9 +814,8 @@ func TestProgramDriftRequiresAtomicInstallationReconciliation(t *testing.T) {
if err := json.Unmarshal(afterSuccess, &legacyState); err != nil {
t.Fatal(err)
}
legacyState["schema_version"] = float64(4)
delete(legacyState, "planning_package_fingerprint")
delete(legacyState, "control_bundle_fingerprint")
legacyState["schema_version"] = float64(6)
delete(legacyState, "program_human_identity_role")
legacyRaw, err := json.MarshalIndent(legacyState, "", " ")
if err != nil {
t.Fatal(err)
Expand All @@ -834,7 +833,7 @@ func TestProgramDriftRequiresAtomicInstallationReconciliation(t *testing.T) {
if err != nil {
t.Fatal(err)
}
legacyPin.StateSchemaVersion = 4
legacyPin.StateSchemaVersion = 6
legacyPinRaw, err = boatstackruntime.EncodePin(legacyPin)
if err != nil {
t.Fatal(err)
Expand Down Expand Up @@ -869,7 +868,7 @@ func TestProgramDriftRequiresAtomicInstallationReconciliation(t *testing.T) {
updatedState.Delivery != priorState.Delivery || updatedState.Workspace != priorState.Workspace || updatedState.Plan != priorState.Plan ||
updatedState.Configuration != priorState.Configuration || updatedState.Publication != priorState.Publication || updatedState.Verification != priorState.Verification ||
updatedState.Terminal != priorState.Terminal || updatedState.PlanFingerprint != priorState.PlanFingerprint || updatedState.ApprovalFingerprint != priorState.ApprovalFingerprint {
t.Fatalf("schema-4 update changed existing product facets: before=%#v after=%#v", priorState, updatedState)
t.Fatalf("base-schema update changed existing product facets: before=%#v after=%#v", priorState, updatedState)
}
updatedPinRaw, err := os.ReadFile(legacyPinPath)
if err != nil {
Expand Down
6 changes: 6 additions & 0 deletions release-notes/2026-08-17-durable-state-schema-migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
### Preserve durable state during named-role upgrades

Boatstack now promotes the immediately preceding durable state schema 6 to
schema 7 while preserving its planning and control-bundle fingerprints. This
allows existing installations to adopt named human identity roles without
misclassifying valid schema-6 state as an unsupported older version.
Loading