diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 0e6d87d..c709fa1 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -721,6 +721,17 @@ incidental text snapshots. Terminal failures appear once, including in quiet. ## Stage 18: Add useful sub-stage progress +**Completed.** Audio acquisition reports actual transfer starts, validated spool +completion, and cache reuse. Transcription and analysis report individual durable +checkpoint completions and validated reuse during partial execution, while paths, +source identity, and reuse decisions remain Info. All messages use the existing +invocation-safe seam and finish with the workers; no ledger or durable schema was +added. Native progress-only and combined-context fixtures verify concurrent +speakers, selective retry, artifacts, audio cache reuse, failed downloads, and +checkpoint-save failures without false completions or multiple final reports. +Focused race, native reporting/checkpoint/resume, configuration/stage/audio/ +artifact, build, and diff checks pass with Go 1.27.4. + Read: existing audio acquisition/materialization, `internal/stage/transcribe.go`, `analyze*.go`, checkpoint reconciliation, and the reporting seam from Stage 17. diff --git a/internal/app/substage_progress_test.go b/internal/app/substage_progress_test.go new file mode 100644 index 0000000..2a1c97f --- /dev/null +++ b/internal/app/substage_progress_test.go @@ -0,0 +1,200 @@ +package app + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "gitea.maximumdirect.net/eric/narratio/internal/adapters/storage" + "gitea.maximumdirect.net/eric/narratio/internal/adapters/whisperx" + "gitea.maximumdirect.net/eric/narratio/internal/artifacts" + "gitea.maximumdirect.net/eric/narratio/internal/config" + "gitea.maximumdirect.net/eric/narratio/internal/manifest" + "go.maximumdirect.net/commandkit" +) + +func executeProgressCommand(t *testing.T, app *commandkit.App, args []string) (runReport, string) { + t.Helper() + var out, diagnostic bytes.Buffer + outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &diagnostic}) + if outcome.Status != 0 { + t.Fatalf("outcome=%#v diagnostics=%s", outcome, diagnostic.String()) + } + var report runReport + if err := json.Unmarshal(out.Bytes(), &report); err != nil { + t.Fatalf("expected one final JSON report: %v; %s", err, out.String()) + } + if !report.Complete { + t.Fatalf("incomplete report=%#v", report) + } + return report, diagnostic.String() +} + +func TestNativeProgressTracksDownloadsConcurrentSpeakersAndReuse(t *testing.T) { + root := t.TempDir() + pipeline, campaign, session := writeValidConfigFiles(t, root) + data, err := os.ReadFile(pipeline) + if err != nil { + t.Fatal(err) + } + mustWriteTestFile(t, pipeline, strings.Replace(string(data), "concurrency: 1", "concurrency: 2", 1)) + mustWriteTestFile(t, session, "session_id: 2026-05-03\ninputs:\n audio_s3: {prefix: audio/}\n") + store := &storage.FakeBackend{} + loaded, err := config.LoadPipelineWithOptions(pipeline, config.PipelineLoadOptions{}) + if err != nil { + t.Fatal(err) + } + prefix := artifacts.S3SessionPrefix(loaded.Storage.S3.RootPrefix, "sample-campaign", "2026-05-03") + for _, speaker := range []string{"a", "b", "c", "d"} { + store.SeedObject(storage.FakeObject{Key: prefix + "audio/" + speaker + ".flac", Data: []byte("synthetic-audio-" + speaker), ETag: "synthetic-generation"}) + } + transcriber := &whisperx.FakeClient{TranscribeFn: func(_ context.Context, req whisperx.TranscribeRequest) (whisperx.TranscribeResult, error) { + return writeTranscribeRecoveryResult(req) + }} + app, err := newApplication(commandDependencies{}, func(ctx context.Context, cfg *config.Config, plan BoundedPlan, opts RunOptions) (*RunSummary, error) { + opts.Env = &Env{WhisperX: transcriber, ObjectStore: store} + return executePlan(ctx, cfg, plan, opts) + }) + if err != nil { + t.Fatal(err) + } + common := []string{"--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--format", "json", "--progress"} + _, diagnostic := executeProgressCommand(t, app, append([]string{"run", "2026-05-03", "--from", "prepare", "--through", "transcribe"}, common...)) + if strings.Count(diagnostic, "downloading audio") != 4 || strings.Count(diagnostic, "audio downloaded") != 4 || strings.Count(diagnostic, "speaker transcription completed") != 4 { + t.Fatalf("missing actual work progress: %s", diagnostic) + } + if strings.Contains(diagnostic, "selected audio source") || strings.Contains(diagnostic, "speaker transcription output") { + t.Fatalf("progress-only enabled contextual information: %s", diagnostic) + } + if len(store.Downloads) != 4 || len(transcriber.RequestsSnapshot()) != 4 { + t.Fatal("progress did not correspond to actual external work") + } + manifestPath := artifacts.SessionManifestPathForCampaign(root, "sample-campaign", "2026-05-03") + saved, err := (&manifest.LocalStore{}).Load(context.Background(), manifestPath) + if err != nil { + t.Fatal(err) + } + paths := artifacts.NewLocalStore(root).SessionPathsFor("sample-campaign", "2026-05-03") + mustWriteTestFile(t, filepath.Join(paths.Root, filepath.FromSlash(saved.Stages["transcribe"].TranscribeSpeakers["b"].Output.LocalPath)), "corrupt") + transcriber = &whisperx.FakeClient{TranscribeFn: func(_ context.Context, req whisperx.TranscribeRequest) (whisperx.TranscribeResult, error) { + return writeTranscribeRecoveryResult(req) + }} + args := append([]string{"run", "2026-05-03", "--stage", "transcribe", "--verbose"}, common...) + _, diagnostic = executeProgressCommand(t, app, args) + if strings.Count(diagnostic, "reusing speaker transcription") != 3 || strings.Count(diagnostic, "speaker transcription completed") != 1 || !strings.Contains(diagnostic, "speaker transcription reuse decision") { + t.Fatalf("missing partial reuse/completion context: %s", diagnostic) + } + if got := requestedTranscribeSpeakers(transcriber); len(got) != 1 || got[0] != "b" { + t.Fatalf("unexpected repeated work=%v", got) + } + _, diagnostic = executeProgressCommand(t, app, append([]string{"run", "2026-05-03", "--stage", "prepare", "--force"}, common...)) + if strings.Count(diagnostic, "reusing cached audio") != 4 || strings.Contains(diagnostic, "downloading audio") || len(store.Downloads) != 4 { + t.Fatalf("cache reuse claimed new downloads: %s", diagnostic) + } + store.SeedObject(storage.FakeObject{Key: prefix + "audio/a.flac", Data: []byte("replacement-audio"), ETag: "new-generation"}) + cause := errors.New("audio download failed") + store.DownloadErr = cause + var out, diagnostics bytes.Buffer + outcome := app.Execute(context.Background(), append([]string{"run", "2026-05-03", "--stage", "prepare", "--force"}, common...), commandkit.Streams{Out: &out, Err: &diagnostics}) + if outcome.Status != 1 || !errors.Is(outcome.Cause, cause) || strings.Count(diagnostics.String(), "downloading audio") != 1 || strings.Contains(diagnostics.String(), "audio downloaded") { + t.Fatalf("failed download progress: outcome=%#v diagnostics=%s", outcome, diagnostics.String()) + } + +} + +func TestNativeProgressTracksArtifactCheckpointsAndReuse(t *testing.T) { + root := t.TempDir() + pipeline, campaign, session := writeArtifactProgressConfig(t, root) + path := artifacts.SessionManifestPathForCampaign(root, "sample-campaign", "2026-05-03") + runner := &analyzeCheckpointRunner{} + app, err := newApplication(commandDependencies{}, func(ctx context.Context, cfg *config.Config, plan BoundedPlan, opts RunOptions) (*RunSummary, error) { + opts.Env = &Env{Scriptorium: runner} + return executePlan(ctx, cfg, plan, opts) + }) + if err != nil { + t.Fatal(err) + } + args := []string{"run", "2026-05-03", "--stage", "analyze", "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--format", "json", "--progress"} + _, diagnostic := executeProgressCommand(t, app, args) + if strings.Count(diagnostic, "artifact completed") != 2 || strings.Contains(diagnostic, "artifact output") { + t.Fatalf("incorrect progress-only artifact messages: %s", diagnostic) + } + saved, err := (&manifest.LocalStore{}).Load(context.Background(), path) + if err != nil { + t.Fatal(err) + } + paths := artifacts.NewLocalStore(root).SessionPathsFor("sample-campaign", "2026-05-03") + mustWriteTestFile(t, filepath.Join(paths.Root, filepath.FromSlash(saved.Stages["analyze"].AnalyzeArtifacts["beta"].Output.LocalPath)), "changed") + runner = &analyzeCheckpointRunner{} + _, diagnostic = executeProgressCommand(t, app, append(args, "--verbose")) + if strings.Count(diagnostic, "reusing artifact") != 1 || strings.Count(diagnostic, "artifact completed") != 1 || !strings.Contains(diagnostic, "artifact reuse decision") || !strings.Contains(diagnostic, "artifact output") { + t.Fatalf("incorrect artifact reuse/completion messages: %s", diagnostic) + } + if len(runner.Calls) != 1 || runner.Calls[0] != "beta" { + t.Fatalf("repeated valid artifact work=%v", runner.Calls) + } +} + +func writeArtifactProgressConfig(t *testing.T, root string) (string, string, string) { + t.Helper() + pipeline, campaign, session := writeValidConfigFiles(t, root) + data, err := os.ReadFile(pipeline) + if err != nil { + t.Fatal(err) + } + mustWriteTestFile(t, pipeline, string(data)+`scriptorium: + artifacts: + alpha: {enabled: true, prompt_id: alpha, output_path: artifacts/alpha.md} + beta: {enabled: true, prompt_id: beta, output_path: artifacts/beta.md} +`) + plan, err := BuildBoundedPlan("analyze", "analyze") + if err != nil { + t.Fatal(err) + } + seed := manifest.New("2026-05-03", time.Now().UTC()) + seed.Campaign = "sample-campaign" + for _, name := range plan.PrefixNames() { + seed.MarkStageSucceeded(name, time.Now().UTC(), nil) + } + path := artifacts.SessionManifestPathForCampaign(root, seed.Campaign, seed.SessionID) + if err := (&manifest.LocalStore{}).Save(context.Background(), path, seed); err != nil { + t.Fatal(err) + } + return pipeline, campaign, session +} + +func TestNativeProgressDoesNotAdvertiseUnsavedArtifact(t *testing.T) { + root := t.TempDir() + pipeline, campaign, session := writeArtifactProgressConfig(t, root) + cause := errors.New("artifact checkpoint unavailable") + store := ¤tAnalyzeCheckpointFailingStore{Store: &manifest.LocalStore{}, CurrentLimit: 1, Err: cause} + runner := &analyzeCheckpointRunner{} + app, err := newApplication(commandDependencies{}, func(ctx context.Context, cfg *config.Config, plan BoundedPlan, opts RunOptions) (*RunSummary, error) { + opts.Env = &Env{Scriptorium: runner, ManifestStore: store} + return executePlan(ctx, cfg, plan, opts) + }) + if err != nil { + t.Fatal(err) + } + var out, diagnostic bytes.Buffer + outcome := app.Execute(context.Background(), []string{"run", "2026-05-03", "--stage", "analyze", "--config", pipeline, "--campaign-file", campaign, "--session-file", session, "--progress", "--format", "json"}, commandkit.Streams{Out: &out, Err: &diagnostic}) + if outcome.Status != 1 || !errors.Is(outcome.Cause, cause) || strings.Contains(diagnostic.String(), "artifact completed") { + t.Fatalf("unsaved completion: outcome=%#v diagnostics=%s", outcome, diagnostic.String()) + } + if len(runner.Calls) != 1 || runner.Calls[0] != "alpha" { + t.Fatalf("unexpected adapter work=%v", runner.Calls) + } + var report runReport + if err := json.Unmarshal(out.Bytes(), &report); err != nil { + t.Fatal(err) + } + if report.Complete || len(report.AvailableArtifacts) != 0 { + t.Fatalf("uncommitted output advertised: %#v", report) + } +} diff --git a/internal/audio/s3_audio.go b/internal/audio/s3_audio.go index 4221178..ff7bc16 100644 --- a/internal/audio/s3_audio.go +++ b/internal/audio/s3_audio.go @@ -11,10 +11,12 @@ import ( "gitea.maximumdirect.net/eric/narratio/internal/adapters/storage" "gitea.maximumdirect.net/eric/narratio/internal/artifacts" "gitea.maximumdirect.net/eric/narratio/internal/fileops" + "gitea.maximumdirect.net/eric/narratio/internal/logging" ) // S3MaterializeRequest describes one S3-backed audio materialization. type S3MaterializeRequest struct { + Reporter logging.Reporter Store storage.ObjectStore Object storage.ObjectInfo Bucket string @@ -50,6 +52,9 @@ func MaterializeS3Audio(ctx context.Context, req S3MaterializeRequest) (S3Materi return S3MaterializeResult{}, fmt.Errorf("destination path is required") } + if req.Reporter != nil { + req.Reporter.Info("selected audio source", "bucket", req.Bucket, "key", key, "destination", req.DestPath) + } result := S3MaterializeResult{} if req.CacheEnabled && cacheIdentityEligible(req) { cachePath, err := artifacts.S3AudioCachePath(req.CacheRoot, req.Bucket, key) @@ -62,6 +67,9 @@ func MaterializeS3Audio(ctx context.Context, req S3MaterializeRequest) (S3Materi } else if ok { result.Checksum = checksum result.CacheHit = true + if req.Reporter != nil { + req.Reporter.Progress("reusing cached audio", "audio", filepath.Base(req.DestPath)) + } return result, nil } } @@ -70,7 +78,7 @@ func MaterializeS3Audio(ctx context.Context, req S3MaterializeRequest) (S3Materi if spoolPath == "" { return S3MaterializeResult{}, fmt.Errorf("spool path is required for s3 audio download") } - if err := downloadObjectAtomic(ctx, req.Store, key, spoolPath, req.Object.Size); err != nil { + if err := downloadObjectAtomic(ctx, req.Store, key, spoolPath, req.Object.Size, req.Reporter); err != nil { return S3MaterializeResult{}, fmt.Errorf("download s3 audio object %q: %w", key, err) } @@ -115,8 +123,11 @@ func validateLocalAudio(path string, expectedSize int64) error { return nil } -func downloadObjectAtomic(ctx context.Context, store storage.ObjectStore, key, destPath string, expectedSize int64) error { +func downloadObjectAtomic(ctx context.Context, store storage.ObjectStore, key, destPath string, expectedSize int64, reporter logging.Reporter) error { temporaryPath, err := writeAudioTemp(destPath, func(destination io.Writer) error { + if reporter != nil { + reporter.Progress("downloading audio", "audio", filepath.Base(destPath)) + } return storage.DownloadTo(ctx, store, key, destination) }) if err != nil { @@ -129,6 +140,9 @@ func downloadObjectAtomic(ctx context.Context, store storage.ObjectStore, key, d if err := fileops.InstallSiblingTempFile(temporaryPath, destPath, fileops.WorkspaceFileMode); err != nil { return err } + if reporter != nil { + reporter.Progress("audio downloaded", "audio", filepath.Base(destPath)) + } return nil } diff --git a/internal/stage/analyze.go b/internal/stage/analyze.go index 2c894cb..01db796 100644 --- a/internal/stage/analyze.go +++ b/internal/stage/analyze.go @@ -140,6 +140,11 @@ func (analyzeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) (*S return nil, fmt.Errorf("analyze: checkpoint reconciled artifact collection before execution: %w", err) } + for _, item := range workPlan.ReusedCurrent { + env.Info("artifact reuse decision", "artifact", item.Key, "reason", item.Reason, "role", item.Role) + env.Progress("reusing artifact", "artifact", item.Key) + } + for _, item := range workPlan.ExecutionOrder { if err := ctx.Err(); err != nil { return nil, err diff --git a/internal/stage/analyze_execution_state.go b/internal/stage/analyze_execution_state.go index 32d003a..6b16464 100644 --- a/internal/stage/analyze_execution_state.go +++ b/internal/stage/analyze_execution_state.go @@ -103,6 +103,8 @@ func (state *analyzeExecutionState) acceptArtifact( state.records = manifest.CloneAnalyzeArtifactCollection(state.committedRecords) return fmt.Errorf("analyze: checkpoint artifact %q: %w", plan.Name, err) } + state.execution.Env.Info("artifact output", "artifact", plan.Name, "source", sourceID, "path", result.Output.AbsolutePath) + state.execution.Env.Progress("artifact completed", "artifact", plan.Name) return nil } diff --git a/internal/stage/prepare.go b/internal/stage/prepare.go index b6aef50..45ea2fc 100644 --- a/internal/stage/prepare.go +++ b/internal/stage/prepare.go @@ -461,6 +461,7 @@ func materializeS3AudioInputs(ctx context.Context, env *Env, m *manifest.Manifes spoolPath := filepath.Join(spoolAudioDir, base) workPath := filepath.Join(workAudioDir, base) result, err := audio.MaterializeS3Audio(ctx, audio.S3MaterializeRequest{ + Reporter: env.Reporter, Store: env.ObjectStore, Object: obj, Bucket: strings.TrimSpace(env.Config.Pipeline.Storage.S3.Bucket), diff --git a/internal/stage/transcribe.go b/internal/stage/transcribe.go index d42c44f..8c1b8e6 100644 --- a/internal/stage/transcribe.go +++ b/internal/stage/transcribe.go @@ -59,6 +59,13 @@ func (transcribeStage) Run(ctx context.Context, env *Env, m *manifest.Manifest) return nil, fmt.Errorf("transcribe: checkpoint reconciled speaker collection before execution: %w", err) } + for _, job := range reconciliation.jobs { + if record, ok := reconciliation.current[job.speakerID]; ok { + env.Info("speaker transcription reuse decision", "speaker", job.speakerID, "output", record.Output.LocalPath) + env.Progress("reusing speaker transcription", "speaker", job.speakerID) + } + } + jobs := append([]transcribeReconciliationJob(nil), reconciliation.work...) if len(jobs) > 0 && env.WhisperX == nil { return nil, fmt.Errorf("transcribe: whisperx adapter is required") diff --git a/internal/stage/transcribe_execution_state.go b/internal/stage/transcribe_execution_state.go index 702aa44..463fdc1 100644 --- a/internal/stage/transcribe_execution_state.go +++ b/internal/stage/transcribe_execution_state.go @@ -136,6 +136,8 @@ func (state *transcribeExecutionState) acceptSpeaker( state.completed++ state.perFile[job.speakerID] = cloneStringAnyMap(metadata) state.runOutputs[job.speakerID] = job.runOutputPath + state.env.Info("speaker transcription output", "speaker", job.speakerID, "path", job.canonicalOutputPath) + state.env.Progress("speaker transcription completed", "speaker", job.speakerID) return nil }