Enforce bounded run prerequisites

This commit is contained in:
2026-08-29 18:17:05 +00:00
parent 3bcf2c08dd
commit 966b95b176
11 changed files with 509 additions and 32 deletions

View File

@@ -0,0 +1,62 @@
package app
import (
"context"
"fmt"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/manifest"
)
func validateBoundedPrerequisites(plan BoundedPlan, m *manifest.Manifest) error {
if !plan.HasExplicitBounds() {
return nil
}
for _, name := range plan.PrefixNames() {
status := "absent"
if m != nil && m.Stages != nil && m.Stages[name] != nil {
stageStatus := m.Stages[name].Status
if stageStatus == manifest.StatusSucceeded || stageStatus == manifest.StatusSkipped {
continue
}
if stageStatus != "" {
status = string(stageStatus)
}
}
return fmt.Errorf(
"prerequisite stage %q has unusable status %q before selected start %q; widen the range with --from %s or recover %s explicitly",
name,
status,
plan.From(),
name,
name,
)
}
return nil
}
func inspectBoundedPrerequisites(ctx context.Context, cfg *config.Config, plan BoundedPlan, store manifest.Store) error {
if !plan.HasExplicitBounds() || len(plan.PrefixNames()) == 0 {
return nil
}
if cfg == nil || cfg.Pipeline == nil || cfg.Session == nil {
return fmt.Errorf("bounded prerequisite inspection requires resolved pipeline and session configuration")
}
if store == nil {
store = &manifest.LocalStore{}
}
path := artifacts.SessionManifestPathForCampaign(
cfg.Pipeline.Workspace.Root,
cfg.Session.Campaign,
cfg.Session.SessionID,
)
m, present, err := loadManifestAtPathIfPresent(ctx, store, path)
if err != nil {
return err
}
if !present {
m = nil
}
return validateBoundedPrerequisites(plan, m)
}

View File

@@ -0,0 +1,288 @@
package app
import (
"context"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"time"
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/manifest"
"gitea.maximumdirect.net/eric/narratio/internal/stage"
)
func TestValidateBoundedPrerequisitesRejectsFirstUnusablePrefixStatus(t *testing.T) {
plan := mustBoundedPlan(t, "render", "extract")
now := time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC)
for _, test := range []struct {
name string
status manifest.StageStatus
want string
}{
{name: "absent", want: "absent"},
{name: "pending", status: manifest.StatusPending, want: "pending"},
{name: "running", status: manifest.StatusRunning, want: "running"},
{name: "failed", status: manifest.StatusFailed, want: "failed"},
{name: "stale", status: manifest.StatusStale, want: "stale"},
{name: "interrupted", status: manifest.StatusInterrupted, want: "interrupted"},
} {
t.Run(test.name, func(t *testing.T) {
m := manifest.New("session", now)
if test.status != "" {
m.Stages["prepare"] = &manifest.StageRecord{Name: "prepare", Status: test.status}
}
// A later terminal prefix must not hide the first unusable one.
m.MarkStageSucceeded("transcribe", now, nil)
err := validateBoundedPrerequisites(plan, m)
if err == nil {
t.Fatal("validateBoundedPrerequisites() error = nil")
}
for _, detail := range []string{`stage "prepare"`, `status "` + test.want + `"`, `selected start "render"`, "--from prepare", "recover prepare"} {
if !strings.Contains(err.Error(), detail) {
t.Fatalf("error = %q, want detail %q", err, detail)
}
}
})
}
}
func TestValidateBoundedPrerequisitesAcceptsSucceededAndSkippedPrefix(t *testing.T) {
plan := mustBoundedPlan(t, "render", "render")
m := manifest.New("session", time.Now().UTC())
for index, name := range plan.PrefixNames() {
if index%2 == 0 {
m.MarkStageSucceeded(name, time.Now().UTC(), nil)
} else {
m.MarkStageSkipped(name, time.Now().UTC(), "not applicable")
}
}
if err := validateBoundedPrerequisites(plan, m); err != nil {
t.Fatalf("validateBoundedPrerequisites() error = %v", err)
}
}
func TestValidateBoundedPrerequisitesHasNoPrefixAtPrepareAndIgnoresSuffix(t *testing.T) {
preparePlan := mustBoundedPlan(t, "prepare", "prepare")
if err := validateBoundedPrerequisites(preparePlan, nil); err != nil {
t.Fatalf("prepare prerequisite validation error = %v", err)
}
renderPlan := mustBoundedPlan(t, "render", "render")
m := manifest.New("session", time.Now().UTC())
markPrefixSucceeded(m, renderPlan)
m.MarkStageFailed("analyze", time.Now().UTC(), "later failure")
if err := validateBoundedPrerequisites(renderPlan, m); err != nil {
t.Fatalf("suffix status affected prerequisite validation: %v", err)
}
}
func TestExecuteStagesRejectsBoundedPrerequisitesBeforePersistentMutation(t *testing.T) {
cfg := testConfig(t)
plan := mustBoundedPlan(t, "render", "render")
m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
m.Campaign = cfg.Session.Campaign
m.MarkStageRunning("prepare", time.Now().UTC())
manifestPath := saveBoundedManifest(t, cfg, m)
before, err := os.ReadFile(manifestPath)
if err != nil {
t.Fatalf("read seeded manifest: %v", err)
}
store := &prerequisiteMutationSpy{local: &manifest.LocalStore{}}
runs := 0
_, err = executeStages(context.Background(), cfg, []stage.Stage{countingStage{name: "render", runs: &runs}}, RunOptions{
Plan: plan,
Env: &Env{ManifestStore: store},
})
if err == nil || !strings.Contains(err.Error(), `stage "prepare" has unusable status "running"`) {
t.Fatalf("executeStages() error = %v, want running prerequisite", err)
}
if runs != 0 || store.creates != 0 || store.saves != 0 {
t.Fatalf("runs=%d manifest creates=%d saves=%d, want no mutation", runs, store.creates, store.saves)
}
after, err := os.ReadFile(manifestPath)
if err != nil {
t.Fatalf("read manifest after rejection: %v", err)
}
if string(after) != string(before) {
t.Fatal("manifest changed after prerequisite rejection")
}
if _, err := os.Stat(artifacts.SessionRunsDirForCampaign(cfg.Pipeline.Workspace.Root, cfg.Session.Campaign, cfg.Session.SessionID)); !os.IsNotExist(err) {
t.Fatalf("runs directory stat error = %v, want not exist", err)
}
}
func TestExecuteStagesBoundedCompositionUsesOnlySelectedCollaborators(t *testing.T) {
for _, test := range []struct {
name string
stageName string
configure func(*config.Config)
assertProbe func(*testing.T, *stage.Env)
}{
{
name: "render",
stageName: "render",
assertProbe: func(t *testing.T, env *stage.Env) {
if env.Seriatim == nil || env.Notarius != nil || env.Scriptorium != nil {
t.Fatalf("render collaborators: seriatim=%v notarius=%v scriptorium=%v", env.Seriatim, env.Notarius, env.Scriptorium)
}
},
},
{
name: "extract",
stageName: "extract",
configure: func(cfg *config.Config) {
cfg.Pipeline.Notarius = &config.NotariusConfig{Enabled: true}
},
assertProbe: func(t *testing.T, env *stage.Env) {
if env.Notarius == nil || env.Scriptorium != nil || env.Seriatim != nil {
t.Fatalf("extract collaborators: notarius=%v scriptorium=%v seriatim=%v", env.Notarius, env.Scriptorium, env.Seriatim)
}
},
},
{
name: "analyze",
stageName: "analyze",
assertProbe: func(t *testing.T, env *stage.Env) {
if env.Scriptorium == nil || env.Notarius != nil || env.Seriatim != nil || env.WhisperX != nil || env.Audita != nil {
t.Fatalf("analyze collaborators: scriptorium=%v notarius=%v seriatim=%v whisperx=%v audita=%v", env.Scriptorium, env.Notarius, env.Seriatim, env.WhisperX, env.Audita)
}
},
},
} {
t.Run(test.name, func(t *testing.T) {
cfg := testConfig(t)
if test.configure != nil {
test.configure(cfg)
}
plan := mustBoundedPlan(t, test.stageName, test.stageName)
m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
m.Campaign = cfg.Session.Campaign
markPrefixSucceeded(m, plan)
saveBoundedManifest(t, cfg, m)
var captured *stage.Env
_, err := executeStages(context.Background(), cfg, []stage.Stage{collaboratorProbeStage{name: test.stageName, captured: &captured}}, RunOptions{Plan: plan})
if err != nil {
t.Fatalf("executeStages() error = %v", err)
}
if captured == nil {
t.Fatal("selected stage did not run")
}
test.assertProbe(t, captured)
})
}
}
func TestExecuteStagesBoundedForceStalesButDoesNotRunDependentsOutsideRange(t *testing.T) {
cfg := testConfig(t)
plan := mustBoundedPlan(t, "render", "render")
m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
m.Campaign = cfg.Session.Campaign
for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim", "render", "extract", "analyze", "publish", "notify"} {
m.MarkStageSucceeded(name, time.Now().UTC(), nil)
}
saveBoundedManifest(t, cfg, m)
runs := 0
_, err := executeStages(context.Background(), cfg, []stage.Stage{countingStage{name: "render", runs: &runs}}, RunOptions{Plan: plan, Force: true})
if err != nil {
t.Fatalf("executeStages() error = %v", err)
}
if runs != 1 {
t.Fatalf("selected render runs = %d, want 1", runs)
}
loaded, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPathFor(cfg))
if err != nil {
t.Fatalf("load manifest: %v", err)
}
for _, name := range []string{"analyze", "publish", "notify"} {
if loaded.Stages[name].Status != manifest.StatusStale {
t.Fatalf("stage %q status = %q, want stale", name, loaded.Stages[name].Status)
}
}
if loaded.Stages["extract"].Status != manifest.StatusSucceeded {
t.Fatalf("extract status = %q, want succeeded", loaded.Stages["extract"].Status)
}
}
func TestExecuteStagesBoundedFailureStopsWithinSelectedRange(t *testing.T) {
cfg := testConfig(t)
plan := mustBoundedPlan(t, "render", "extract")
m := manifest.New(cfg.Session.SessionID, time.Now().UTC())
m.Campaign = cfg.Session.Campaign
markPrefixSucceeded(m, plan)
saveBoundedManifest(t, cfg, m)
extractRuns := 0
_, err := executeStages(context.Background(), cfg, []stage.Stage{
failingStage{name: "render", err: errors.New("render failed")},
countingStage{name: "extract", runs: &extractRuns},
}, RunOptions{Plan: plan})
if err == nil || !strings.Contains(err.Error(), "render failed") {
t.Fatalf("executeStages() error = %v", err)
}
if extractRuns != 0 {
t.Fatalf("extract runs = %d, want 0", extractRuns)
}
}
type collaboratorProbeStage struct {
name string
captured **stage.Env
}
func (s collaboratorProbeStage) Name() string { return s.name }
func (s collaboratorProbeStage) Run(_ context.Context, env *stage.Env, _ *manifest.Manifest) (*stage.StageResult, error) {
*s.captured = env
return &stage.StageResult{}, nil
}
type prerequisiteMutationSpy struct {
local *manifest.LocalStore
creates int
saves int
}
func (s *prerequisiteMutationSpy) Create(ctx context.Context, sessionID string) (*manifest.Manifest, error) {
s.creates++
return s.local.Create(ctx, sessionID)
}
func (s *prerequisiteMutationSpy) Load(ctx context.Context, path string) (*manifest.Manifest, error) {
return s.local.Load(ctx, path)
}
func (s *prerequisiteMutationSpy) Save(ctx context.Context, path string, m *manifest.Manifest) error {
s.saves++
return s.local.Save(ctx, path, m)
}
func mustBoundedPlan(t *testing.T, from, through string) BoundedPlan {
t.Helper()
plan, err := BuildBoundedPlan(from, through)
if err != nil {
t.Fatalf("BuildBoundedPlan(%q, %q) error = %v", from, through, err)
}
return plan
}
func markPrefixSucceeded(m *manifest.Manifest, plan BoundedPlan) {
for _, name := range plan.PrefixNames() {
m.MarkStageSucceeded(name, time.Now().UTC(), nil)
}
}
func saveBoundedManifest(t *testing.T, cfg *config.Config, m *manifest.Manifest) string {
t.Helper()
path := manifestPathFor(cfg)
if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
t.Fatalf("create manifest directory: %v", err)
}
if err := (&manifest.LocalStore{}).Save(context.Background(), path, m); err != nil {
t.Fatalf("save manifest: %v", err)
}
return path
}

View File

@@ -8,8 +8,10 @@ import (
"reflect"
"strings"
"testing"
"time"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/manifest"
"gitea.maximumdirect.net/eric/narratio/internal/stage"
)
@@ -141,6 +143,15 @@ func TestRunPassesBoundedPlanToRunner(t *testing.T) {
func TestPlanPrintsOnlyBoundedRange(t *testing.T) {
workspaceRoot := t.TempDir()
pipelinePath, campaignPath, sessionPath := writeValidConfigFiles(t, workspaceRoot)
m := manifest.New("2026-05-03", time.Date(2026, 5, 3, 10, 0, 0, 0, time.UTC))
m.Campaign = "sample-campaign"
for _, name := range []string{"prepare", "transcribe", "merge", "polish", "normalize", "trim"} {
m.MarkStageSucceeded(name, time.Date(2026, 5, 3, 10, 1, 0, 0, time.UTC), nil)
}
manifestPath := filepath.Join(workspaceRoot, "work", "sample-campaign", "2026-05-03", "manifest.json")
if err := (&manifest.LocalStore{}).Save(context.Background(), manifestPath, m); err != nil {
t.Fatalf("save prerequisite manifest: %v", err)
}
var out bytes.Buffer
err := Plan(context.Background(), []string{
"2026-05-03",

View File

@@ -12,7 +12,6 @@ import (
"gitea.maximumdirect.net/eric/narratio/internal/artifacts"
"gitea.maximumdirect.net/eric/narratio/internal/config"
"gitea.maximumdirect.net/eric/narratio/internal/logging"
"gitea.maximumdirect.net/eric/narratio/internal/manifest"
)
// Plan validates configuration, prepares the local workdir, and prints stage order.
@@ -37,6 +36,13 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
if _, err := resolveEffectiveArtifacts(cfg, request.SelectedArtifacts); err != nil {
return fmt.Errorf("plan: %w", err)
}
m, err := loadManifestIfPresent(ctx, cfg)
if err != nil {
return fmt.Errorf("plan: %w", err)
}
if err := validateBoundedPrerequisites(request.Plan, m); err != nil {
return fmt.Errorf("plan: %w", err)
}
if _, err := loadSecretsFromConfig(cfg, logging.NewLogger(os.Stderr, slog.LevelInfo)); err != nil {
return fmt.Errorf("plan: %w", err)
}
@@ -48,11 +54,6 @@ func Plan(ctx context.Context, args []string, out io.Writer) error {
}
stages := request.Plan.Stages()
var m *manifest.Manifest
m, err = loadManifestIfPresent(ctx, cfg)
if err != nil {
return fmt.Errorf("plan: %w", err)
}
decisions := decideStageActions(stages, m, request.Force)
runCount := 0

View File

@@ -146,7 +146,12 @@ func TestPostPublishCleanupRetriesWhenInitialObligationSaveFails(t *testing.T) {
store.fail = nil
if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("retry executeStages() error = %v", err)
t.Fatalf("non-publish executeStages() error = %v", err)
}
assertExists(t, seed.spoolAudioDir)
assertCleanupPending(t, cfg)
if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Force: true, Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("publish retry executeStages() error = %v", err)
}
assertMissing(t, seed.spoolAudioDir)
assertCleanupComplete(t, cfg)
@@ -178,7 +183,12 @@ func TestPostPublishCleanupRetriesFailedDeletionWithoutTouchingOtherRuns(t *test
removeRunScopedDirFn = originalRemove
if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("retry executeStages() error = %v", err)
t.Fatalf("non-publish executeStages() error = %v", err)
}
assertExists(t, seed.runWorkDir)
assertCleanupPending(t, cfg)
if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Force: true, Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("publish retry executeStages() error = %v", err)
}
assertMissing(t, seed.runWorkDir)
assertExists(t, seed.otherRunDir)
@@ -218,12 +228,16 @@ func TestPostPublishCleanupRetriesWhenCompletionEvidenceSaveFails(t *testing.T)
store.fail = nil
if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("retry executeStages() error = %v", err)
t.Fatalf("non-publish executeStages() error = %v", err)
}
assertCleanupPending(t, cfg)
if _, err := executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Force: true, Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("publish retry executeStages() error = %v", err)
}
assertCleanupComplete(t, cfg)
if _, err := executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ManifestStore: store, ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("idempotent retry executeStages() error = %v", err)
t.Fatalf("idempotent non-publish executeStages() error = %v", err)
}
assertMissing(t, seed.spoolAudioDir)
}
@@ -328,7 +342,10 @@ func TestPostPublishCleanupFailsOnUnsafePath(t *testing.T) {
t.Fatalf("Save() error = %v", err)
}
_, err = executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}})
if _, err = executeStages(context.Background(), cfg, nil, RunOptions{Env: &Env{ObjectStore: &storage.FakeBackend{}}}); err != nil {
t.Fatalf("non-publish executeStages() error = %v", err)
}
_, err = executeStages(context.Background(), cfg, []stage.Stage{publishSuccessStage{}}, RunOptions{Force: true, Env: &Env{ObjectStore: &storage.FakeBackend{}}})
if err == nil || !strings.Contains(err.Error(), "refusing to delete path outside root") {
t.Fatalf("executeStages() error = %v, want safe-path failure", err)
}

View File

@@ -44,6 +44,13 @@ type RunSummary struct {
var executeStagesFn = executeStages
func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage, opts RunOptions) (summary *RunSummary, resultErr error) {
var prerequisiteStore manifest.Store
if opts.Env != nil {
prerequisiteStore = opts.Env.ManifestStore
}
if err := inspectBoundedPrerequisites(ctx, cfg, opts.Plan, prerequisiteStore); err != nil {
return nil, fmt.Errorf("validate bounded run prerequisites: %w", err)
}
effectiveArtifacts := opts.EffectiveArtifacts
if !effectiveArtifacts.Resolved() && cfg != nil && cfg.Pipeline != nil && cfg.Pipeline.Scriptorium != nil {
var err error
@@ -170,7 +177,7 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
fmt.Errorf("load secrets from files: %w", err),
)
}
if env.WhisperX == nil {
if env.WhisperX == nil && stagesContainAny(stages, "transcribe") {
client, err := buildDefaultWhisperXClient(env.Config)
if err != nil {
return nil, persistTerminalFailure(
@@ -180,7 +187,7 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
}
env.WhisperX = client
}
if env.Seriatim == nil {
if env.Seriatim == nil && stagesContainAny(stages, "merge", "normalize", "trim", "render") {
runner, err := buildDefaultSeriatimRunner(env.Config)
if err != nil {
return nil, persistTerminalFailure(
@@ -190,7 +197,7 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
}
env.Seriatim = runner
}
if env.Audita == nil {
if env.Audita == nil && stagesContainAny(stages, "polish") {
runner, err := buildDefaultAuditaRunner(env.Config)
if err != nil {
return nil, persistTerminalFailure(
@@ -203,7 +210,7 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
if env.Notarius == nil && needsNotariusForRun(env.Config, stages) {
env.Notarius = notarius.NewSubprocessRunner()
}
if env.Scriptorium == nil {
if env.Scriptorium == nil && stagesContainAny(stages, "trim", "analyze") {
env.Scriptorium = scriptorium.NewSubprocessRunner()
}
if env.ObjectStore == nil && needsObjectStoreForRun(env.Config, stages, effectiveArtifacts) {
@@ -233,7 +240,7 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
return config.MergePublishLockRules(staticLocks, remote.Locks), nil
}
}
if env.Notifier == nil {
if env.Notifier == nil && stagesContainAny(stages, "notify") {
env.Notifier = &notify.NoopSender{}
}
@@ -426,11 +433,13 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
// The run record lives inside the run work directory, which cleanup may
// remove. Persist its completed publishing result before cleanup starts so a
// successful deletion cannot be undone by a later diagnostic write.
if err := runPostPublishCleanup(ctx, env, manifestPath, m, executed); err != nil {
return nil, persistPostPublishCleanupFailure(
ctx, env.ManifestStore, manifestPath, m,
fmt.Errorf("post-publish cleanup incomplete: %w", err),
)
if containsStage(executed, "publish") {
if err := runPostPublishCleanup(ctx, env, manifestPath, m, executed); err != nil {
return nil, persistPostPublishCleanupFailure(
ctx, env.ManifestStore, manifestPath, m,
fmt.Errorf("post-publish cleanup incomplete: %w", err),
)
}
}
return &RunSummary{
@@ -444,6 +453,22 @@ func executeStages(ctx context.Context, cfg *config.Config, stages []stage.Stage
}, nil
}
func stagesContainAny(stages []stage.Stage, names ...string) bool {
wanted := make(map[string]struct{}, len(names))
for _, name := range names {
wanted[name] = struct{}{}
}
for _, candidate := range stages {
if candidate == nil {
continue
}
if _, ok := wanted[candidate.Name()]; ok {
return true
}
}
return false
}
func persistPostPublishCleanupFailure(
ctx context.Context,
sessionStore manifest.Store,