eric/notarius
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add stable checkpoint decision diagnostics

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-22 02:13:50 +00:00
parent 5bdd56cfb1
commit 9de399432e
10 changed files with 391 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
internal/framework/checkpoint/filesystem_test.go
View File

@@ -8,6 +8,7 @@ import (
"runtime"
"strings"
"testing"
"unicode/utf8"
"gitea.maximumdirect.net/eric/notarius/internal/core/source"
"gitea.maximumdirect.net/eric/notarius/internal/framework/contracts"
@@ -137,7 +138,7 @@ func TestFilesystemCheckpointRejectsMissingAndCorruptState(t *testing.T) {
if err := os.Remove(stage.manifest(fixture)); err != nil {
t.Fatal(err)
}
assertStageNotReused(t, stage, fixture, "missing")
assertStageNotReused(t, stage, fixture, pipeline.CheckpointReasonMissing)
})
t.Run(stage.name+" malformed manifest", func(t *testing.T) {
@@ -145,7 +146,7 @@ func TestFilesystemCheckpointRejectsMissingAndCorruptState(t *testing.T) {
if err := os.WriteFile(stage.manifest(fixture), []byte("{"), 0o600); err != nil {
t.Fatal(err)
}
assertStageNotReused(t, stage, fixture, "decode")
assertStageNotReused(t, stage, fixture, pipeline.CheckpointReasonDecodeFailed)
})
}
}
@@ -154,18 +155,18 @@ func TestFilesystemCheckpointRejectsIncompatibleManifests(t *testing.T) {
for _, tt := range []struct {
name string
edit func(map[string]any)
want string
want pipeline.CheckpointReasonCode
}{
{"v1 schema", func(m map[string]any) { m["workspace_schema_version"] = WorkspaceSchemaVersionV1 }, "workspace schema"},
{"v2 schema", func(m map[string]any) { m["workspace_schema_version"] = WorkspaceSchemaVersionV2 }, "workspace schema"},
{"unknown schema", func(m map[string]any) { m["workspace_schema_version"] = "notarius.workspace.future" }, "workspace schema"},
{"identity", func(m map[string]any) { m["metadata"].(map[string]any)["checkpoint_identity_digest"] = "sha256:other" }, "identity"},
{"stage", func(m map[string]any) { m["stage"] = string(StageMerge) }, "stage"},
{"lane", func(m map[string]any) { m["lane_id"] = "lane-other" }, "lane"},
{"module", func(m map[string]any) { m["module_key"] = "module-other" }, "module"},
{"v1 schema", func(m map[string]any) { m["workspace_schema_version"] = WorkspaceSchemaVersionV1 }, pipeline.CheckpointReasonWorkspaceSchemaIncompatible},
{"v2 schema", func(m map[string]any) { m["workspace_schema_version"] = WorkspaceSchemaVersionV2 }, pipeline.CheckpointReasonWorkspaceSchemaIncompatible},
{"unknown schema", func(m map[string]any) { m["workspace_schema_version"] = "notarius.workspace.future" }, pipeline.CheckpointReasonWorkspaceSchemaIncompatible},
{"identity", func(m map[string]any) { m["metadata"].(map[string]any)["checkpoint_identity_digest"] = "sha256:other" }, pipeline.CheckpointReasonIdentityMismatch},
{"stage", func(m map[string]any) { m["stage"] = string(StageMerge) }, pipeline.CheckpointReasonStageMismatch},
{"lane", func(m map[string]any) { m["lane_id"] = "lane-other" }, pipeline.CheckpointReasonLaneMismatch},
{"module", func(m map[string]any) { m["module_key"] = "module-other" }, pipeline.CheckpointReasonModuleMismatch},
{"dependency", func(m map[string]any) {
m["dependency_fingerprints"] = []map[string]string{{"name": "input", "value": "other"}}
}, "dependency"},
}, pipeline.CheckpointReasonDependencyMismatch},
} {
t.Run(tt.name, func(t *testing.T) {
fixture := seedFilesystemCheckpoints(t)
@@ -180,7 +181,7 @@ func TestFilesystemCheckpointRejectsNonTerminalStatuses(t *testing.T) {
t.Run(string(status), func(t *testing.T) {
fixture := seedFilesystemCheckpoints(t)
editManifest(t, checkpointStages()[1].manifest(fixture), func(m map[string]any) { m["status"] = string(status) })
assertStageNotReused(t, checkpointStages()[1], fixture, "status")
assertStageNotReused(t, checkpointStages()[1], fixture, pipeline.CheckpointReasonStatusNotReusable)
})
}
}
@@ -189,20 +190,20 @@ func TestFilesystemCheckpointRejectsIncompleteArtifactsAndContent(t *testing.T)
for _, tt := range []struct {
name string
edit func(map[string]any)
want string
want pipeline.CheckpointReasonCode
}{
{"artifact kind", func(m map[string]any) { m["outputs"].([]any)[0].(map[string]any)["artifact_kind"] = "" }, "artifact codec identity"},
{"schema id", func(m map[string]any) { m["outputs"].([]any)[0].(map[string]any)["schema"].(map[string]any)["id"] = "" }, "artifact codec identity"},
{"artifact kind", func(m map[string]any) { m["outputs"].([]any)[0].(map[string]any)["artifact_kind"] = "" }, pipeline.CheckpointReasonArtifactCodecIncompatible},
{"schema id", func(m map[string]any) { m["outputs"].([]any)[0].(map[string]any)["schema"].(map[string]any)["id"] = "" }, pipeline.CheckpointReasonArtifactCodecIncompatible},
{"schema version", func(m map[string]any) {
m["outputs"].([]any)[0].(map[string]any)["schema"].(map[string]any)["version"] = ""
}, "artifact codec identity"},
{"schema digest", func(m map[string]any) { m["outputs"].([]any)[0].(map[string]any)["schema_digest"] = "" }, "artifact codec identity"},
}, pipeline.CheckpointReasonArtifactCodecIncompatible},
{"schema digest", func(m map[string]any) { m["outputs"].([]any)[0].(map[string]any)["schema_digest"] = "" }, pipeline.CheckpointReasonArtifactCodecIncompatible},
{"base64", func(m map[string]any) {
m["outputs"].([]any)[0].(map[string]any)["content"].(map[string]any)["content_base64"] = "%"
}, "base64"},
}, pipeline.CheckpointReasonArtifactPayloadInvalid},
{"content digest", func(m map[string]any) {
m["outputs"].([]any)[0].(map[string]any)["content"].(map[string]any)["content_digest"] = "sha256:other"
}, "content digest"},
}, pipeline.CheckpointReasonArtifactDigestMismatch},
} {
t.Run(tt.name, func(t *testing.T) {
fixture := seedFilesystemCheckpoints(t)
@@ -218,7 +219,7 @@ func TestFilesystemCheckpointRejectsSourceAndOutputDigestMismatches(t *testing.T
editJSON(t, filepath.Join(fixture.root, mustRelativePath(t, fixture.identity), "source", "source-document.json"), func(m map[string]any) {
m["document"].(map[string]any)["units"].([]any)[0].(map[string]any)["text"] = ""
})
assertStageNotReused(t, checkpointStages()[0], fixture, "source checkpoint document")
assertStageNotReused(t, checkpointStages()[0], fixture, pipeline.CheckpointReasonArtifactPayloadInvalid)
})
t.Run("source output digest", func(t *testing.T) {
@@ -226,7 +227,7 @@ func TestFilesystemCheckpointRejectsSourceAndOutputDigestMismatches(t *testing.T
editJSON(t, filepath.Join(fixture.root, mustRelativePath(t, fixture.identity), "source", "source-document.json"), func(m map[string]any) {
m["document"].(map[string]any)["digest"] = "sha256:other"
})
assertStageNotReused(t, checkpointStages()[0], fixture, "output digest")
assertStageNotReused(t, checkpointStages()[0], fixture, pipeline.CheckpointReasonArtifactDigestMismatch)
})
for _, stage := range checkpointStages()[1:] {
@@ -235,7 +236,7 @@ func TestFilesystemCheckpointRejectsSourceAndOutputDigestMismatches(t *testing.T
editManifest(t, stage.manifest(fixture), func(m map[string]any) {
m["output_digests"].([]any)[0].(map[string]any)["value"] = "sha256:other"
})
assertStageNotReused(t, stage, fixture, "output digest")
assertStageNotReused(t, stage, fixture, pipeline.CheckpointReasonArtifactDigestMismatch)
})
}
}
@@ -259,6 +260,68 @@ func TestFilesystemCheckpointDependencyDecisionIsBoundedAndCategorized(t *testin
}
}
func TestFilesystemCheckpointDecisionFamiliesAreStableAndSafe(t *testing.T) {
const secretSentinel = "do-not-expose-checkpoint-secret"
tests := []struct {
name string
prepare func(*testing.T, filesystemCheckpointFixture) pipeline.CheckpointDecision
category pipeline.CheckpointDecisionCategory
code pipeline.CheckpointReasonCode
}{
{"loading disabled", func(t *testing.T, _ filesystemCheckpointFixture) pipeline.CheckpointDecision {
_, decision := pipeline.NoopCheckpointLoader().Source("source")
return decision
}, pipeline.CheckpointDecisionExecuted, pipeline.CheckpointReasonLoadingDisabled},
{"checkpoint unavailable", func(t *testing.T, fixture filesystemCheckpointFixture) pipeline.CheckpointDecision {
if err := os.Remove(checkpointStages()[1].manifest(fixture)); err != nil {
t.Fatal(err)
}
return checkpointStages()[1].load(fixture)
}, pipeline.CheckpointDecisionExecuted, pipeline.CheckpointReasonMissing},
{"workspace identity", func(t *testing.T, fixture filesystemCheckpointFixture) pipeline.CheckpointDecision {
editManifest(t, checkpointStages()[1].manifest(fixture), func(m map[string]any) {
m["workspace_schema_version"] = secretSentinel
})
return checkpointStages()[1].load(fixture)
}, pipeline.CheckpointDecisionExecuted, pipeline.CheckpointReasonWorkspaceSchemaIncompatible},
{"manifest scope", func(t *testing.T, fixture filesystemCheckpointFixture) pipeline.CheckpointDecision {
editManifest(t, checkpointStages()[1].manifest(fixture), func(m map[string]any) { m["module_key"] = secretSentinel })
return checkpointStages()[1].load(fixture)
}, pipeline.CheckpointDecisionExecuted, pipeline.CheckpointReasonModuleMismatch},
{"dependency invalidated", func(t *testing.T, fixture filesystemCheckpointFixture) pipeline.CheckpointDecision {
_, decision := fixture.loader.Extract("lane-a", "extract-module", []pipeline.CheckpointFingerprint{{Name: "input", Value: secretSentinel}})
return decision
}, pipeline.CheckpointDecisionDependencyInvalidated, pipeline.CheckpointReasonDependencyMismatch},
{"artifact payload", func(t *testing.T, fixture filesystemCheckpointFixture) pipeline.CheckpointDecision {
editJSON(t, filepath.Join(fixture.root, mustRelativePath(t, fixture.identity), "extract", "lane-a", "outputs.json"), func(m map[string]any) {
m["outputs"].([]any)[0].(map[string]any)["artifact_kind"] = ""
m["outputs"].([]any)[0].(map[string]any)["source_id"] = secretSentinel
})
return checkpointStages()[1].load(fixture)
}, pipeline.CheckpointDecisionExecuted, pipeline.CheckpointReasonArtifactCodecIncompatible},
{"checkpoint reused", func(t *testing.T, fixture filesystemCheckpointFixture) pipeline.CheckpointDecision {
return checkpointStages()[1].load(fixture)
}, pipeline.CheckpointDecisionReused, pipeline.CheckpointReasonReused},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
fixture := seedFilesystemCheckpoints(t)
decision := test.prepare(t, fixture)
if decision.Category != test.category || decision.ReasonCode != test.code {
t.Fatalf("decision = %#v, want category %q and code %q", decision, test.category, test.code)
}
if len([]byte(decision.Detail)) > 512 || !utf8.ValidString(decision.Detail) {
t.Fatalf("decision detail is not bounded valid UTF-8: %#v", decision)
}
for _, forbidden := range []string{secretSentinel, fixture.root} {
if strings.Contains(decision.Detail, forbidden) || strings.Contains(decision.Reason, forbidden) {
t.Fatalf("decision leaked %q: %#v", forbidden, decision)
}
}
})
}
}
type checkpointStage struct {
name string
manifest func(filesystemCheckpointFixture) string
@@ -367,11 +430,11 @@ func checkpointArtifact(module, content string) pipeline.CheckpointArtifact {
}
}
func assertStageNotReused(t *testing.T, stage checkpointStage, fixture filesystemCheckpointFixture, want string) {
func assertStageNotReused(t *testing.T, stage checkpointStage, fixture filesystemCheckpointFixture, want pipeline.CheckpointReasonCode) {
t.Helper()
decision := stage.load(fixture)
if decision.Reused || !strings.Contains(strings.ToLower(decision.Reason), strings.ToLower(want)) {
t.Fatalf("%s decision=%#v, want non-reused reason containing %q", stage.name, decision, want)
if decision.Reused || decision.ReasonCode != want {
t.Fatalf("%s decision=%#v, want non-reused reason code %q", stage.name, decision, want)
}
}