From 868006040095bd2a0de8e7a20faaad0b8b656ff2 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 22 Nov 2026 02:49:48 +0000 Subject: [PATCH] Record debug evidence in one run-scoped capture session --- docs/roadmap/implementation.md | 25 ++ internal/cli/run.go | 211 +++++---------- internal/cli/run_debug.go | 51 ++++ internal/cli/run_debug_test.go | 119 +++++++++ internal/cli/run_terminal.go | 95 ------- internal/core/debugbundle/bundle.go | 70 +++-- internal/core/debugbundle/bundle_test.go | 300 +++++++--------------- internal/core/debugbundle/summary.go | 145 ----------- internal/framework/debug/recorder.go | 159 ++++++++++-- internal/framework/debug/recorder_test.go | 201 ++++++++++++--- 10 files changed, 700 insertions(+), 676 deletions(-) create mode 100644 internal/cli/run_debug.go create mode 100644 internal/cli/run_debug_test.go delete mode 100644 internal/cli/run_terminal.go delete mode 100644 internal/core/debugbundle/summary.go diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 6da19355..ce28755d 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1389,6 +1389,31 @@ counting, and evidence source order/window behavior. ## Stage 30: Build The Debug Recorder And Session Lifecycle +**Status:** Complete. Replaced summary/trace allocation and separate terminal +writers with one run-scoped recorder for incremental JSON/text evidence and one +terminal outcome. Allocation creates the absolute run directory and atomically +updates a relative latest link at start; completion never retargets it. Failed +starts retain an available directory rather than deleting captured data. +The recorder is concurrency-safe, retains callback errors for boundary checks, +preserves primary causes alongside capture failures, and finalizes once without +rewriting evidence on repeated calls. Finalization failures are errors, including +after artifact publication; a later presentation failure remains reportable. +Added reusable native debug/debug-dir input binding and selection, preserving +quiet/debug ordering, explicit false/empty values, configured/default roots, +invocation-relative overrides, and nonempty overrides over empty configuration. +Disabled capture performs no allocation or latest update. Removed the legacy +summary/terminal factories and routed run-path allocation/finalization through +the new lifecycle before engine/preflight and before successful presentation. +Real-filesystem lifecycle/concurrency/failure tests, isolated real-CommandKit +flag/selection tests, focused pipeline tests, selected vet/race checks, production +debug/bundle/pipeline/config builds, and git diff checks pass. Full CLI/pipeline +package checks remain blocked at setup by unmigrated imports of the removed +reporting package and old ConfigKit's YAML plugin/limit dependency; their results +are not claimed passing. Full native evidence/observation wiring remains Stage 31, +native run-handler composition remains Stage 33, and final publication/report +outcome integration remains Stage 34. Remaining obsolete fixtures are Stage 35 +cleanup, not a reason to restore the old writers. + **Goal:** requested capture has one simple recorder and explicit failure semantics. **Inspect/change:** `internal/core/debugbundle`, `internal/framework/debug`, diff --git a/internal/cli/run.go b/internal/cli/run.go index b50aa08d..5541f5cf 100644 --- a/internal/cli/run.go +++ b/internal/cli/run.go @@ -18,7 +18,6 @@ import ( "gitea.maximumdirect.net/eric/notarius/internal/buildinfo" "gitea.maximumdirect.net/eric/notarius/internal/core/artifacts" "gitea.maximumdirect.net/eric/notarius/internal/core/config" - "gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle" "gitea.maximumdirect.net/eric/notarius/internal/core/fileio" "gitea.maximumdirect.net/eric/notarius/internal/framework/artifactcache" "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" @@ -31,18 +30,16 @@ import ( ) type Options struct { - LLMClient promptkit.LLMClient - LLMRuntime promptkit.RuntimeConfig - Catalog pipeline.ModuleCatalog - Registries pipeline.Registries - LLMClientFactory LLMClientFactory - RunIDGenerator RunIDGenerator - LookupEnv func(string) (string, bool) - Now func() time.Time - UserCacheDir func() (string, error) - DebugRecorderFactory func(string) (pipeline.DebugRecorder, error) - DebugTerminalFactory func(*debugbundle.SummaryWriter) DebugTerminalWriter - promptKitAssets *frameworkllm.AssetRegistry + LLMClient promptkit.LLMClient + LLMRuntime promptkit.RuntimeConfig + Catalog pipeline.ModuleCatalog + Registries pipeline.Registries + LLMClientFactory LLMClientFactory + RunIDGenerator RunIDGenerator + LookupEnv func(string) (string, bool) + Now func() time.Time + UserCacheDir func() (string, error) + promptKitAssets *frameworkllm.AssetRegistry } type LLMRuntimeOverrides struct { @@ -83,12 +80,6 @@ func normalizeOptions(opts Options) (Options, error) { if opts.UserCacheDir == nil { opts.UserCacheDir = os.UserCacheDir } - if opts.DebugRecorderFactory == nil { - opts.DebugRecorderFactory = frameworkdebug.NewFilesystemRecorder - } - if opts.DebugTerminalFactory == nil { - opts.DebugTerminalFactory = func(writer *debugbundle.SummaryWriter) DebugTerminalWriter { return writer } - } if isEmptyCatalog(opts.Catalog) && isEmptyRegistries(opts.Registries) { components, err := newProductionComponents() if err != nil { @@ -158,18 +149,10 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i fmt.Fprintln(stderr, "notarius: run requires --input") return 2 } - if strings.TrimSpace(*debugDir) != "" && !*debug { - fmt.Fprintln(stderr, "notarius: --debug-dir requires --debug") - return 2 - } if strings.TrimSpace(*outputDir) == "" && flagWasProvided(args, "--output-dir") { fmt.Fprintln(stderr, "notarius: --output-dir must not be empty") return 2 } - if strings.TrimSpace(*debugDir) == "" && flagWasProvided(args, "--debug-dir") { - fmt.Fprintln(stderr, "notarius: --debug-dir must not be empty") - return 2 - } if requestedSessionID.set && strings.TrimSpace(requestedSessionID.value) == "" { fmt.Fprintln(stderr, "notarius: --session-id must not be empty") return 2 @@ -210,7 +193,7 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i return 2 } - loaded, loadedConfigPath, err := loadConfigKit(*configPath, *configOverlay, runConfigurationOverrides(*outputDir, *debugDir), opts) + loaded, loadedConfigPath, err := loadConfigKit(*configPath, *configOverlay, runConfigurationOverrides(*outputDir), opts) if err != nil { writeConfigLoadError(stderr, err) return 1 @@ -231,52 +214,48 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i return 1 } runOutputDir := filepath.Join(cfg.Output.Directory, runID) - commandState := newPipelineCommandState(runID, pipelineID, runOutputDir) - var summary *debugbundle.SummaryWriter - var terminalWriter DebugTerminalWriter - debugPath := "" - debugRecorder := pipeline.NoopDebugRecorder() - if *debug { - bundle, err := debugbundle.Allocate(cfg.Debug.Directory, runID, startedAt) - if err != nil { - fmt.Fprintf(stderr, "notarius: %v\n", err) - return 1 - } - debugPath, summary = bundle.Path(), bundle.Summary() - commandState.setDebugPath(debugPath) - terminalWriter = opts.DebugTerminalFactory(summary) - if terminalWriter == nil { - terminalWriter = summary - } - debugRecorder, err = opts.DebugRecorderFactory(bundle.TraceRoot()) - if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("create debug recorder: %w", err)) - } - debugRecorder = pipeline.SynchronizedDebugRecorder(debugRecorder) + + var capture *frameworkdebug.Recorder + var output pipeline.RunOutput + published := false + captureOutcome := func() any { + return map[string]any{"pipeline": pipelineID, "output_directory": runOutputDir, "artifact_count": output.ArtifactCount(), "fallback_count": output.FallbackCount, "published": published} } - invocation := debugbundle.Invocation{ - Operation: "run", - PipelineID: pipelineID, - InputPath: strings.TrimSpace(*inputPath), - ConfigPath: loadedConfigPath, - ConfigSource: configSource(*configPath), - ConfigOverlay: effectiveConfigOverlay(*configOverlay), - OnlyLanes: append([]string(nil), only...), - ReasoningEffortOverride: runtimeOverrides.ReasoningEffort, - RunID: runID, - StartedAt: startedAt, + fail := func(primary error, extra ...error) int { + cause := errors.Join(append([]error{primary}, extra...)...) + cause = capture.Finalize(captureOutcome(), cause) + fmt.Fprintf(stderr, "notarius: %v\n", cause) + if published { + fmt.Fprintf(stderr, "notarius: artifacts=%s\n", runOutputDir) + } + if capture.Path() != "" { + fmt.Fprintf(stderr, "notarius: debug=%s\n", capture.Path()) + } + return 1 } - if err := writeSummary(summary, func() error { return summary.WriteInvocation(invocation) }); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug invocation metadata: %w", err)) + capture, err = startRunDebug(runDebugInput{ + Enabled: commandkit.Supplied[bool]{Value: *debug, Set: flagWasProvided(args, "--debug")}, + Directory: commandkit.Supplied[string]{Value: *debugDir, Set: flagWasProvided(args, "--debug-dir")}, + }, cfg.Debug.Directory, runID, startedAt) + if err != nil { + return fail(err) + } + debugPath := capture.Path() + var debugRecorder pipeline.DebugRecorder = pipeline.NoopDebugRecorder() + if capture.Enabled() { + debugRecorder = capture + } + if err := capture.WriteJSON("context.json", map[string]any{"pipeline": pipelineID, "input_path": *inputPath, "config_path": loadedConfigPath, "run_id": runID, "started_at": startedAt}); err != nil { + return fail(err) } catalog, err := effectiveCatalog(opts) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } referenceOverrides, referenceUnbinds, err := resolveCLIReferenceRequests(cfg, pipelineID, only, catalog, referenceRequests, referenceUnbindRequests) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } effective, err := cfg.Resolve(config.ResolveInput{ PipelineID: pipelineID, @@ -287,43 +266,28 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i ReferenceUnbinds: referenceUnbinds, }) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } profileIDs := effectiveLLMProfileIDs(effective.ResolvedPipeline) if err := validateExplicitPromptKitProfiles(context.Background(), effective.Config, profileIDs, opts.promptKitAssets); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } workingDir, err := os.Getwd() if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("resolve working directory: %w", err)) + return fail(fmt.Errorf("resolve working directory: %w", err)) } materialized, referenceDiagnostics, err := pipeline.MaterializeReferences(effective.ResolvedPipeline, catalog, pipeline.ReferenceMaterializationOptions{ ConfigPath: loadedConfigPath, WorkingDir: workingDir, }) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } effective.ResolvedPipeline = materialized - invocation.PipelineDigest = effective.ResolvedPipeline.Digest - if err := writeSummary(summary, func() error { return summary.WriteInvocation(invocation) }); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug invocation metadata: %w", err)) - } - if err := writeSummary(summary, func() error { return summary.WriteEffectiveConfig(loaded) }); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug effective config: %w", err)) - } - if err := writeSummary(summary, func() error { return summary.WriteResolvedPipeline(effective) }); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug resolved pipeline: %w", err)) - } - if err := writeSummary(summary, func() error { - return summary.WriteResolvedReferences(pipeline.ReferenceProvenance(effective.ResolvedPipeline)) - }); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug resolved references: %w", err)) - } registries, err := effectiveRegistries(opts) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } ctx := context.Background() @@ -333,31 +297,27 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i } llmClient, llmProfiles, err := opts.LLMClientFactory(ctx, effective.Config, factoryProfileID, runtimeOverrides) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("create LLM client for profile %q: %w", factoryProfileID, err)) + return fail(fmt.Errorf("create LLM client for profile %q: %w", factoryProfileID, err)) } llmClient = pipeline.WithDebugLLMRecording(llmClient, debugRecorder) prepared, err := pipeline.Prepare(effective.ResolvedPipeline, registries, pipeline.ModuleDependencies{LLM: llmClient}) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("prepare pipeline %q: %w", pipelineID, err)) + return fail(fmt.Errorf("prepare pipeline %q: %w", pipelineID, err)) } rawInput, err := os.ReadFile(strings.TrimSpace(*inputPath)) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("read input %q: %w", strings.TrimSpace(*inputPath), err)) + return fail(fmt.Errorf("read input %q: %w", strings.TrimSpace(*inputPath), err)) } effectiveSessionID, err := resolvePromptSessionID(requestedSessionID.value, effective.ResolvedPipeline.Input.Module, rawInput) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) - } - invocation.SessionID = effectiveSessionID - if err := writeSummary(summary, func() error { return summary.WriteInvocation(invocation) }); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug invocation metadata: %w", err)) + return fail(err) } cache, err := artifactcache.NewFilesystemStore(effective.Config.CacheDirectory) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } - output, err := pipeline.New().Run(ctx, pipeline.RunInput{ + output, err = pipeline.New().Run(ctx, pipeline.RunInput{ Prepared: prepared, Path: strings.TrimSpace(*inputPath), RawInput: rawInput, @@ -372,52 +332,42 @@ func runPipelineCommand(args []string, stdout, stderr io.Writer, opts Options) i Workers: cfg.Concurrency.Workers, }) diagnosticProjection, diagnosticErr := contracts.ProjectDiagnosticCollection(output.Diagnostics) - if diagnosticErr == nil { - commandState.observeOutput(output, diagnosticProjection) - } if err != nil { primaryErr := fmt.Errorf("run pipeline %q: %w", pipelineID, err) - if output.Manifest.PipelineID != "" { - if summaryErr := writePartialSummary(summary, output); summaryErr != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, primaryErr, fmt.Errorf("write debug summary: %w", summaryErr)) - } - } if diagnosticErr != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, primaryErr, fmt.Errorf("summarize run diagnostics: %w", diagnosticErr)) + return fail(primaryErr, fmt.Errorf("summarize run diagnostics: %w", diagnosticErr)) } - return failPipelineCommand(stderr, commandState, terminalWriter, primaryErr) + return fail(primaryErr) } if diagnosticErr != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("summarize run diagnostics: %w", diagnosticErr)) + return fail(fmt.Errorf("summarize run diagnostics: %w", diagnosticErr)) } - if err := writePartialSummary(summary, output); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, fmt.Errorf("write debug summary: %w", err)) - } var encodedResult []byte if *machineOutput { result, err := newRunResultWithDiagnostics(effective.ResolvedPipeline, output, runOutputDir, debugPath, diagnosticProjection) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } encodedResult, err = encodeRunResult(result) if err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } } if err := writeOutputFiles(runOutputDir, output.OutputFiles); err != nil { - return failPipelineCommand(stderr, commandState, terminalWriter, err) + return fail(err) } - if primaryErr, persistenceErr := commandState.terminalize(terminalWriter, nil); primaryErr != nil { - return writePipelineCommandFailure(stderr, commandState, primaryErr, persistenceErr) + published = true + if err := capture.Finalize(captureOutcome(), nil); err != nil { + return fail(err) } if *machineOutput { if err := writeRunResult(stdout, encodedResult); err != nil { - return writePipelineCommandFailure(stderr, commandState, errors.New("write run result"), nil) + return fail(errors.New("write run result")) } } else { - fmt.Fprintf(stdout, "pipeline %q complete: outputs=%d rejected=%d output=%s\n", effective.PipelineID, len(output.NormalizeOutputs), len(output.Rejected), runOutputDir) + fmt.Fprintf(stdout, "pipeline %q complete: artifacts=%d output=%s\n", effective.PipelineID, output.ArtifactCount(), runOutputDir) if debugPath != "" { fmt.Fprintf(stdout, "debug=%s\n", debugPath) } @@ -441,26 +391,6 @@ func logicalOutputFile(files []contracts.OutputFile, name string) (string, bool) return "", false } -func writeSummary(summary *debugbundle.SummaryWriter, write func() error) error { - if summary == nil { - return nil - } - return write() -} - -func writePartialSummary(summary *debugbundle.SummaryWriter, output pipeline.RunOutput) error { - if summary == nil { - return nil - } - if err := summary.WriteRunManifest(output.Manifest); err != nil { - return err - } - if err := summary.WriteDiagnostics(output.Diagnostics); err != nil { - return err - } - return nil -} - func rawInputDigest(data []byte) string { sum := sha256.Sum256(data) return "sha256:" + hex.EncodeToString(sum[:]) @@ -566,7 +496,7 @@ func runFlagTakesValue(arg string) bool { } } -func runConfigurationOverrides(outputDir, debugDir string) []configkit.Override { +func runConfigurationOverrides(outputDir string) []configkit.Override { overrides := make([]configkit.Override, 0, 3) if outputDir = strings.TrimSpace(outputDir); outputDir != "" { overrides = append(overrides, configkit.Override{ @@ -575,13 +505,6 @@ func runConfigurationOverrides(outputDir, debugDir string) []configkit.Override Flag: "--output-dir", }) } - if debugDir = strings.TrimSpace(debugDir); debugDir != "" { - overrides = append(overrides, configkit.Override{ - Path: configkit.Keys("debug", "directory"), - Value: debugDir, - Flag: "--debug-dir", - }) - } return overrides } diff --git a/internal/cli/run_debug.go b/internal/cli/run_debug.go new file mode 100644 index 00000000..a02db007 --- /dev/null +++ b/internal/cli/run_debug.go @@ -0,0 +1,51 @@ +package cli + +import ( + "fmt" + "path/filepath" + "strings" + "time" + + frameworkdebug "gitea.maximumdirect.net/eric/notarius/internal/framework/debug" + "go.maximumdirect.net/commandkit" +) + +type runDebugInput struct { + Enabled commandkit.Supplied[bool] + Directory commandkit.Supplied[string] +} + +func runDebugFlags[I any](selectInput func(*I) *runDebugInput) []commandkit.Flag[I] { + return []commandkit.Flag[I]{ + commandkit.BoolFlag(commandkit.FlagMeta{Name: "debug", Usage: "Capture run evidence."}, false, func(input *I, value commandkit.Supplied[bool]) { selectInput(input).Enabled = value }), + commandkit.ValueFlag(commandkit.FlagMeta{Name: "debug-dir", Usage: "Debug capture directory; empty disables capture."}, (*string)(nil), func(value string) (string, error) { + if strings.ContainsRune(value, '\x00') { + return "", fmt.Errorf("debug directory must not contain NUL") + } + return value, nil + }, func(input *I, value commandkit.Supplied[string]) { selectInput(input).Directory = value }), + } +} + +// The configured directory has already been resolved against its source by the +// application load. CLI paths instead belong to the invocation directory. +func (input runDebugInput) directory(configuredDirectory string) (string, error) { + directory := configuredDirectory + if input.Directory.Set { + directory = input.Directory.Value + } + if !input.Enabled.Value || directory == "" { + return "", nil + } + return filepath.Abs(directory) +} + +// Only the run handler calls this, after configuration/run identity and before +// engine construction or pipeline preflight. Shared loaders never allocate. +func startRunDebug(input runDebugInput, configuredDirectory, runID string, startedAt time.Time) (*frameworkdebug.Recorder, error) { + directory, err := input.directory(configuredDirectory) + if err != nil || directory == "" { + return nil, err + } + return frameworkdebug.Start(directory, runID, startedAt) +} diff --git a/internal/cli/run_debug_test.go b/internal/cli/run_debug_test.go new file mode 100644 index 00000000..911656b2 --- /dev/null +++ b/internal/cli/run_debug_test.go @@ -0,0 +1,119 @@ +package cli + +import ( + "context" + "io" + "os" + "path/filepath" + "testing" + "time" + + "gitea.maximumdirect.net/eric/notarius/internal/core/config" + "go.maximumdirect.net/commandkit" +) + +func TestRunDebugSelectionRetainsNativeBooleanAndSuppliedEmptyDirectory(t *testing.T) { + t.Chdir(t.TempDir()) + configured := filepath.Join(t.TempDir(), "configured") + for _, test := range []struct { + name string + args []string + configured, want string + enabled bool + mode commandkit.ReportingMode + }{ + {"omitted", nil, configured, "", false, commandkit.ReportingModeOrdinary}, + {"directory alone", []string{"--debug-dir", "override"}, configured, "", false, commandkit.ReportingModeOrdinary}, + {"configured directory", []string{"--debug"}, configured, configured, true, commandkit.ReportingModeDebug}, + {"native debug then quiet", []string{"--debug", "--quiet"}, configured, configured, true, commandkit.ReportingModeQuiet}, + {"native quiet then debug", []string{"--quiet", "--debug"}, configured, configured, true, commandkit.ReportingModeDebug}, + {"native debug false", []string{"--debug", "--debug=false"}, configured, "", false, commandkit.ReportingModeOrdinary}, + {"empty configured", []string{"--debug"}, "", "", true, commandkit.ReportingModeDebug}, + {"explicit empty override", []string{"--debug", "--debug-dir", ""}, configured, "", true, commandkit.ReportingModeDebug}, + {"relative override", []string{"--debug", "--debug-dir", "override"}, configured, "override", true, commandkit.ReportingModeDebug}, + {"override reenables empty configured", []string{"--debug", "--debug-dir", "override"}, "", "override", true, commandkit.ReportingModeDebug}, + {"default", []string{"--debug"}, config.Default().Debug.Directory, "/tmp/notarius-debug", true, commandkit.ReportingModeDebug}, + } { + t.Run(test.name, func(t *testing.T) { + called := false + command := commandkit.NewCommand(commandkit.CommandSpec[runDebugInput]{ + Name: "run", Flags: runDebugFlags(func(input *runDebugInput) *runDebugInput { return input }), + Run: func(inv commandkit.Invocation, input runDebugInput) commandkit.Outcome { + called = true + directory, err := input.directory(test.configured) + want := test.want + if want != "" { + want, _ = filepath.Abs(want) + } + if err != nil || directory != want || input.Enabled.Value != test.enabled || inv.ReportingMode() != test.mode { + t.Errorf("directory=%q error=%v input=%#v mode=%v", directory, err, input, inv.ReportingMode()) + } + return commandkit.Success() + }, + }) + app, err := commandkit.New(commandkit.Identity{Name: "test"}, command) + if err != nil { + t.Fatal(err) + } + result := app.Execute(context.Background(), append([]string{"run"}, test.args...), commandkit.Streams{Out: io.Discard, Err: io.Discard}) + if result.Status != 0 || !called { + t.Fatalf("native run input=%#v called=%v", result, called) + } + }) + } +} + +func TestRunDebugStartFailureRetainsAvailablePath(t *testing.T) { + parent := t.TempDir() + if err := os.Mkdir(filepath.Join(parent, "latest"), 0o700); err != nil { + t.Fatal(err) + } + enabled := runDebugInput{Enabled: commandkit.Supplied[bool]{Value: true, Set: true}} + capture, err := startRunDebug(enabled, parent, "run", time.Now()) + if err == nil || capture == nil || capture.Path() != filepath.Join(parent, "run") { + t.Fatalf("start=%#v %v", capture, err) + } + // The run handler must stop here; the partially allocated capture can still + // finalize and report the start failure without engine/provider construction. + if finalErr := capture.Finalize(nil, err); finalErr == nil { + t.Fatal("start failure hidden") + } + if _, err := os.Stat(filepath.Join(capture.Path(), "outcome.json")); err != nil { + t.Fatal(err) + } +} + +func TestDisabledRunDebugDoesNotAllocateOrChangeLatest(t *testing.T) { + root := t.TempDir() + unallocated := filepath.Join(root, "unallocated") + if capture, err := startRunDebug(runDebugInput{}, unallocated, "run", time.Now()); err != nil || capture != nil { + t.Fatalf("disabled capture=%#v %v", capture, err) + } + if _, err := os.Stat(unallocated); !os.IsNotExist(err) { + t.Fatalf("disabled capture created its root: %v", err) + } + first, err := startRunDebug(runDebugInput{Enabled: commandkit.Supplied[bool]{Value: true}}, root, "first", time.Now()) + if err != nil { + t.Fatal(err) + } + for _, input := range []runDebugInput{ + {}, + {Directory: commandkit.Supplied[string]{Value: root, Set: true}}, + {Enabled: commandkit.Supplied[bool]{Value: true}, Directory: commandkit.Supplied[string]{Set: true}}, + } { + capture, err := startRunDebug(input, root, "disabled", time.Now()) + if err != nil || capture != nil { + t.Fatalf("disabled start=%#v %v", capture, err) + } + } + target, err := os.Readlink(filepath.Join(root, "latest")) + if err != nil || target != "first" { + t.Fatalf("disabled run changed latest=%q %v", target, err) + } + if _, err := os.Stat(filepath.Join(root, "disabled")); !os.IsNotExist(err) { + t.Fatalf("disabled capture allocated: %v", err) + } + if err := first.Finalize(nil, nil); err != nil { + t.Fatal(err) + } +} diff --git a/internal/cli/run_terminal.go b/internal/cli/run_terminal.go deleted file mode 100644 index 0ccd9c7a..00000000 --- a/internal/cli/run_terminal.go +++ /dev/null @@ -1,95 +0,0 @@ -package cli - -import ( - "errors" - "fmt" - "io" - - "gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle" - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" - "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" -) - -type DebugTerminalWriter interface { - WriteRunReport(debugbundle.RunReport) error - WriteError(string) error -} - -type pipelineCommandState struct { - report debugbundle.RunReport - terminalized bool -} - -func newPipelineCommandState(runID, pipelineID, outputPath string) *pipelineCommandState { - return &pipelineCommandState{report: debugbundle.RunReport{ - RunID: runID, - PipelineID: pipelineID, - OutputPath: outputPath, - }} -} - -func (s *pipelineCommandState) setDebugPath(debugPath string) { - if s != nil { - s.report.DebugPath = debugPath - } -} - -func (s *pipelineCommandState) observeOutput(output pipeline.RunOutput, diagnostics contracts.DiagnosticProjection) { - if s == nil { - return - } - s.report.OutputCount = len(output.NormalizeOutputs) - s.report.RejectedCount = len(output.Rejected) - s.report.WarningGroupCount = len(diagnostics.Warnings) - s.report.WarningOccurrenceCount = diagnostics.WarningOccurrenceCount - s.report.DiagnosticGroupCount = len(diagnostics.Diagnostics) - s.report.DiagnosticOccurrenceCount = diagnostics.DiagnosticOccurrenceCount - s.report.DiagnosticsTruncated = output.Diagnostics.Truncated - s.report.ValidationStatus = output.Manifest.ValidationStatus -} - -func (s *pipelineCommandState) terminalize(writer DebugTerminalWriter, primaryErr error) (error, error) { - if s == nil || s.terminalized { - return primaryErr, nil - } - s.terminalized = true - if writer == nil { - return primaryErr, nil - } - - report := s.report - report.Succeeded = primaryErr == nil - reportErr := writer.WriteRunReport(report) - if reportErr != nil { - reportErr = fmt.Errorf("write debug run report: %w", reportErr) - if primaryErr == nil { - primaryErr = reportErr - reportErr = nil - } - } - - var errorLogErr error - if primaryErr != nil { - if err := writer.WriteError(primaryErr.Error()); err != nil { - errorLogErr = fmt.Errorf("write debug error log: %w", err) - } - } - return primaryErr, errors.Join(reportErr, errorLogErr) -} - -func failPipelineCommand(stderr io.Writer, state *pipelineCommandState, writer DebugTerminalWriter, primaryErr error, persistenceErrs ...error) int { - primaryErr, terminalErr := state.terminalize(writer, primaryErr) - persistenceErrs = append(persistenceErrs, terminalErr) - return writePipelineCommandFailure(stderr, state, primaryErr, errors.Join(persistenceErrs...)) -} - -func writePipelineCommandFailure(stderr io.Writer, state *pipelineCommandState, primaryErr, persistenceErr error) int { - fmt.Fprintf(stderr, "notarius: %v\n", primaryErr) - if persistenceErr != nil { - fmt.Fprintf(stderr, "notarius: %v\n", persistenceErr) - } - if state != nil && state.report.DebugPath != "" { - fmt.Fprintf(stderr, "notarius: debug=%s\n", state.report.DebugPath) - } - return 1 -} diff --git a/internal/core/debugbundle/bundle.go b/internal/core/debugbundle/bundle.go index 3184f8ff..cd339cdb 100644 --- a/internal/core/debugbundle/bundle.go +++ b/internal/core/debugbundle/bundle.go @@ -1,4 +1,4 @@ -// Package debugbundle owns explicitly requested per-run debug bundles. +// Package debugbundle allocates explicitly requested per-run debug directories. package debugbundle import ( @@ -10,38 +10,54 @@ import ( ) type Bundle struct { - path, summaryRoot, traceRoot string - createdAt time.Time + path string + createdAt time.Time } +// Allocate starts a capture session. A link failure returns the already-created +// bundle as well as the error so callers can identify and retain available data. func Allocate(parent, runID string, startedAt time.Time) (*Bundle, error) { - parent = strings.TrimSpace(parent) if parent == "" { return nil, fmt.Errorf("debug parent must not be empty") } if err := validateRunID(runID); err != nil { return nil, err } + parent, err := filepath.Abs(parent) + if err != nil { + return nil, fmt.Errorf("resolve debug parent: %w", err) + } if err := os.MkdirAll(parent, 0o700); err != nil { return nil, fmt.Errorf("create debug parent %q: %w", parent, err) } - path := filepath.Join(parent, runID) - if err := os.Mkdir(path, 0o700); err != nil { - if os.IsExist(err) { - return nil, fmt.Errorf("debug bundle %q already exists", path) - } - return nil, fmt.Errorf("create debug bundle %q: %w", path, err) + directory := filepath.Join(parent, runID) + if err := os.Mkdir(directory, 0o700); err != nil { + return nil, fmt.Errorf("create debug bundle %q: %w", directory, err) } - summary, trace := filepath.Join(path, "summary"), filepath.Join(path, "trace") - if err := os.Mkdir(summary, 0o700); err != nil { - _ = os.Remove(path) - return nil, fmt.Errorf("create debug summary %q: %w", summary, err) + bundle := &Bundle{path: directory, createdAt: startedAt} + if err := updateLatest(parent, runID); err != nil { + return bundle, fmt.Errorf("update debug latest for %q: %w", directory, err) } - if err := os.Mkdir(trace, 0o700); err != nil { - _ = os.RemoveAll(path) - return nil, fmt.Errorf("create debug trace %q: %w", trace, err) + return bundle, nil +} + +func updateLatest(parent, runID string) error { + temporary, err := os.CreateTemp(parent, ".latest-*") + if err != nil { + return err } - return &Bundle{path: path, summaryRoot: summary, traceRoot: trace, createdAt: startedAt}, nil + name := temporary.Name() + defer os.Remove(name) + if err := temporary.Close(); err != nil { + return err + } + if err := os.Remove(name); err != nil { + return err + } + if err := os.Symlink(runID, name); err != nil { + return err + } + return os.Rename(name, filepath.Join(parent, "latest")) } func validateRunID(runID string) error { @@ -59,18 +75,6 @@ func (b *Bundle) Path() string { } return b.path } -func (b *Bundle) SummaryRoot() string { - if b == nil { - return "" - } - return b.summaryRoot -} -func (b *Bundle) TraceRoot() string { - if b == nil { - return "" - } - return b.traceRoot -} func (b *Bundle) RunID() string { if b == nil { return "" @@ -83,9 +87,3 @@ func (b *Bundle) CreatedAt() time.Time { } return b.createdAt } -func (b *Bundle) Summary() *SummaryWriter { - if b == nil { - return nil - } - return &SummaryWriter{root: b.summaryRoot, runID: b.RunID(), createdAt: b.createdAt} -} diff --git a/internal/core/debugbundle/bundle_test.go b/internal/core/debugbundle/bundle_test.go index 1bbeef83..63661ec7 100644 --- a/internal/core/debugbundle/bundle_test.go +++ b/internal/core/debugbundle/bundle_test.go @@ -1,252 +1,140 @@ package debugbundle import ( - "bytes" - "encoding/json" "errors" - "io" "os" "path/filepath" - "strings" + "sync" "testing" "time" - - "gitea.maximumdirect.net/eric/notarius/internal/core/artifacts" - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" - "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" ) -const testBundleRunID = "run-42-00000000000000000000000000000001" - -func TestAllocateCreatesRestrictiveSummaryAndTrace(t *testing.T) { - parent := t.TempDir() - fixed := time.Unix(0, 42).UTC() - bundle, err := Allocate(parent, testBundleRunID, fixed) +func TestAllocateStartsOneDirectoryWithRelativeLatest(t *testing.T) { + t.Chdir(t.TempDir()) + started := time.Unix(42, 0).UTC() + bundle, err := Allocate("debug root ", "run-first", started) if err != nil { t.Fatal(err) } - if bundle.RunID() != testBundleRunID || bundle.CreatedAt() != fixed || bundle.SummaryRoot() != filepath.Join(bundle.Path(), "summary") || bundle.TraceRoot() != filepath.Join(bundle.Path(), "trace") { + if !filepath.IsAbs(bundle.Path()) || bundle.RunID() != "run-first" || bundle.CreatedAt() != started { t.Fatalf("bundle=%#v", bundle) } - for _, path := range []string{bundle.Path(), bundle.SummaryRoot(), bundle.TraceRoot()} { - info, err := os.Stat(path) - if err != nil { - t.Fatal(err) - } - if info.Mode().Perm() != 0o700 { - t.Fatalf("%s mode=%#o", path, info.Mode().Perm()) - } + names, err := os.ReadDir(bundle.Path()) + if err != nil || len(names) != 0 { + t.Fatalf("unexpected summary/trace hierarchy: %v %v", names, err) } - if err := bundle.Summary().WriteError("failed"); err != nil { - t.Fatal(err) + target, err := os.Readlink(filepath.Join(filepath.Dir(bundle.Path()), "latest")) + if err != nil || target != bundle.RunID() || filepath.IsAbs(target) { + t.Fatalf("latest=%q %v", target, err) } - info, err := os.Stat(filepath.Join(bundle.SummaryRoot(), ArtifactErrorLog)) +} + +func TestAllocateRetainsExistingBundleOnCollision(t *testing.T) { + parent := t.TempDir() + bundle, err := Allocate(parent, "first", time.Now()) if err != nil { t.Fatal(err) } - if info.Mode().Perm() != 0o600 { - t.Fatalf("file mode=%#o", info.Mode().Perm()) - } -} -func TestAllocateRejectsExistingBundleWithoutChangingIt(t *testing.T) { - parent := t.TempDir() - bundlePath := filepath.Join(parent, testBundleRunID) - if err := os.Mkdir(bundlePath, 0o700); err != nil { + sentinel := filepath.Join(bundle.Path(), "sentinel") + if err := os.WriteFile(sentinel, []byte("existing evidence"), 0o600); err != nil { t.Fatal(err) } - sentinelPath := filepath.Join(bundlePath, "sentinel") - sentinel := []byte("existing bundle") - if err := os.WriteFile(sentinelPath, sentinel, 0o600); err != nil { - t.Fatal(err) + if _, err := Allocate(parent, "first", time.Now()); !errors.Is(err, os.ErrExist) { + t.Fatalf("collision=%v", err) } - - if _, err := Allocate(parent, testBundleRunID, time.Unix(0, 42)); err == nil || !strings.Contains(err.Error(), "already exists") { - t.Fatalf("Allocate() error = %v, want collision", err) + got, err := os.ReadFile(sentinel) + if err != nil || string(got) != "existing evidence" { + t.Fatalf("evidence=%q %v", got, err) } - if got, err := os.ReadFile(sentinelPath); err != nil || !bytes.Equal(got, sentinel) { - t.Fatalf("sentinel = %q, %v", got, err) + target, err := os.Readlink(filepath.Join(parent, "latest")) + if err != nil || target != "first" { + t.Fatalf("collision changed latest: %q %v", target, err) } } func TestAllocateRejectsUnsafeRunIDsBeforeCreatingParent(t *testing.T) { - for _, runID := range []string{"", ".", "..", "../escape", `..\\escape`, "/absolute", " trailing "} { - t.Run(runID, func(t *testing.T) { + for _, id := range []string{"", ".", "..", "../escape", "/absolute", " spaced ", string([]byte{'a', 92, 'b'})} { + t.Run(id, func(t *testing.T) { parent := filepath.Join(t.TempDir(), "debug") - if _, err := Allocate(parent, runID, time.Time{}); err == nil { - t.Fatalf("Allocate(%q) succeeded", runID) + if _, err := Allocate(parent, id, time.Now()); err == nil { + t.Fatal("unsafe run ID accepted") } if _, err := os.Stat(parent); !os.IsNotExist(err) { - t.Fatalf("debug parent exists or stat failed: %v", err) + t.Fatalf("parent exists: %v", err) } }) } } -func TestSummaryWriterWritesEverySummaryArtifact(t *testing.T) { - bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42)) - if err != nil { - t.Fatal(err) - } - summary := bundle.Summary() - if err := summary.WriteInvocation(Invocation{Operation: "run"}); err != nil { - t.Fatal(err) - } - if err := summary.WriteEffectiveConfig(testEffectiveConfigWriter{content: "version: 5\n"}); err != nil { - t.Fatal(err) - } - if err := summary.WriteResolvedPipeline(testRedactedResolvedPipelinePayload{}); err != nil { - t.Fatal(err) - } - if err := summary.WriteResolvedReferences(nil); err != nil { - t.Fatal(err) - } - if err := summary.WriteCheckpointEvents(nil); err != nil { - t.Fatal(err) - } - if err := summary.WriteRunManifest(artifacts.RunManifest{RunID: bundle.RunID()}); err != nil { - t.Fatal(err) - } - if err := summary.WriteChunkPlan(artifacts.ChunkPlanSummary{}); err != nil { - t.Fatal(err) - } - if err := summary.WriteRunReport(RunReport{RunID: bundle.RunID(), PipelineID: "test"}); err != nil { - t.Fatal(err) - } - if err := summary.WriteDiagnostics(contracts.DiagnosticCollection{}); err != nil { - t.Fatal(err) - } - if err := summary.WriteError("failed"); err != nil { - t.Fatal(err) - } - - for _, name := range []string{ - ArtifactInvocationMetadata, - ArtifactEffectiveConfigYAML, - ArtifactResolvedPipeline, - ArtifactResolvedReferences, - ArtifactCheckpointEvents, - ArtifactRunManifest, - ArtifactChunkPlan, - ArtifactRunReport, - ArtifactDiagnostics, - ArtifactErrorLog, - } { - info, err := os.Stat(filepath.Join(bundle.SummaryRoot(), name)) - if err != nil { - t.Fatalf("summary artifact %q: %v", name, err) +func TestAllocateFailureLeavesAvailableDataWithoutFallbackOrDeletion(t *testing.T) { + t.Run("parent is a file", func(t *testing.T) { + parent := filepath.Join(t.TempDir(), "debug") + if err := os.WriteFile(parent, []byte("existing"), 0o600); err != nil { + t.Fatal(err) } - if info.Mode().Perm() != 0o600 { - t.Fatalf("summary artifact %q mode=%#o", name, info.Mode().Perm()) + if bundle, err := Allocate(parent, "run", time.Now()); err == nil || bundle != nil { + t.Fatalf("bundle=%#v error=%v", bundle, err) } - } + got, err := os.ReadFile(parent) + if err != nil || string(got) != "existing" { + t.Fatalf("parent changed: %q %v", got, err) + } + }) + t.Run("latest cannot be replaced", func(t *testing.T) { + parent := t.TempDir() + latest := filepath.Join(parent, "latest") + if err := os.Mkdir(latest, 0o700); err != nil { + t.Fatal(err) + } + if err := os.WriteFile(filepath.Join(latest, "sentinel"), []byte("existing"), 0o600); err != nil { + t.Fatal(err) + } + bundle, err := Allocate(parent, "run", time.Now()) + if err == nil || bundle == nil { + t.Fatalf("available bundle lost: %#v %v", bundle, err) + } + if _, err := os.Stat(bundle.Path()); err != nil { + t.Fatal(err) + } + if got, err := os.ReadFile(filepath.Join(latest, "sentinel")); err != nil || string(got) != "existing" { + t.Fatalf("latest directory changed: %q %v", got, err) + } + names, err := os.ReadDir(parent) + if err != nil || len(names) != 2 { + t.Fatalf("temporary link left behind: %v %v", names, err) + } + }) } -func TestWriteEffectiveConfigDoesNotPublishPartialRendering(t *testing.T) { - bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42)) - if err != nil { - t.Fatal(err) +func TestConcurrentAllocationLeavesAllSessionsAndAValidLatestLink(t *testing.T) { + parent := t.TempDir() + const sessions = 8 + var wg sync.WaitGroup + failures := make(chan error, sessions) + for i := range sessions { + wg.Add(1) + go func(i int) { + defer wg.Done() + _, err := Allocate(parent, time.Unix(int64(i), 0).Format("150405"), time.Now()) + failures <- err + }(i) } - if err := bundle.Summary().WriteEffectiveConfig(testEffectiveConfigWriter{err: errors.New("render failed")}); err == nil { - t.Fatal("WriteEffectiveConfig() error = nil, want render failure") - } - path := filepath.Join(bundle.SummaryRoot(), ArtifactEffectiveConfigYAML) - if _, err := os.Stat(path); !os.IsNotExist(err) { - t.Fatalf("effective configuration artifact exists after rendering failure: %v", err) - } -} - -func TestWriteInvocationPreservesReasoningEffortOverrideStates(t *testing.T) { - replacement := "focused" - cleared := "" - tests := []struct { - name string - override *string - wantValue string - wantSet bool - }{ - {name: "inherit"}, - {name: "replace", override: &replacement, wantValue: "focused", wantSet: true}, - {name: "clear", override: &cleared, wantSet: true}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42)) - if err != nil { - t.Fatal(err) - } - if err := bundle.Summary().WriteInvocation(Invocation{ - Operation: "run", - ReasoningEffortOverride: tt.override, - }); err != nil { - t.Fatal(err) - } - data, err := os.ReadFile(filepath.Join(bundle.SummaryRoot(), ArtifactInvocationMetadata)) - if err != nil { - t.Fatal(err) - } - var payload map[string]any - if err := json.Unmarshal(data, &payload); err != nil { - t.Fatal(err) - } - value, found := payload["reasoning_effort_override"] - if found != tt.wantSet || (found && value != tt.wantValue) { - t.Fatalf("reasoning override found=%t value=%#v, want found=%t value=%q; JSON=%s", found, value, tt.wantSet, tt.wantValue, data) - } - }) - } -} - -func TestWriteInvocationOmitsEmptySessionID(t *testing.T) { - for _, sessionID := range []string{"", "session-123"} { - bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42)) + wg.Wait() + close(failures) + for err := range failures { if err != nil { t.Fatal(err) } - if err := bundle.Summary().WriteInvocation(Invocation{Operation: "run", SessionID: sessionID}); err != nil { - t.Fatal(err) - } - data, err := os.ReadFile(filepath.Join(bundle.SummaryRoot(), ArtifactInvocationMetadata)) - if err != nil { - t.Fatal(err) - } - var payload map[string]any - if err := json.Unmarshal(data, &payload); err != nil { - t.Fatal(err) - } - value, found := payload["session_id"] - if found != (sessionID != "") || (found && value != sessionID) { - t.Fatalf("session found=%t value=%#v, want found=%t value=%q; JSON=%s", found, value, sessionID != "", sessionID, data) - } + } + names, err := os.ReadDir(parent) + if err != nil || len(names) != sessions+1 { + t.Fatalf("sessions=%v %v", names, err) + } + target, err := os.Readlink(filepath.Join(parent, "latest")) + if err != nil || filepath.IsAbs(target) { + t.Fatalf("latest=%q %v", target, err) + } + if info, err := os.Stat(filepath.Join(parent, target)); err != nil || !info.IsDir() { + t.Fatalf("latest target unavailable: %v", err) } } -func TestSummaryWriterInternalWritesConfineArtifacts(t *testing.T) { - bundle, err := Allocate(t.TempDir(), testBundleRunID, time.Unix(0, 42)) - if err != nil { - t.Fatal(err) - } - if err := bundle.Summary().writeJSON("../outside.json", map[string]any{}); err == nil { - t.Fatal("accepted traversal") - } - if err := bundle.Summary().writeBytes(`trace\\x`, []byte("x")); err == nil { - t.Fatal("accepted backslash") - } -} - -type testEffectiveConfigWriter struct { - content string - err error -} - -func (writer testEffectiveConfigWriter) WriteEffective(output io.Writer) error { - if writer.err != nil { - return writer.err - } - _, err := io.WriteString(output, writer.content) - return err -} - -type testRedactedResolvedPipelinePayload struct{} - -func (testRedactedResolvedPipelinePayload) RedactedResolvedPipelinePayload() pipeline.ResolvedPipeline { - return pipeline.ResolvedPipeline{ID: "redacted"} -} diff --git a/internal/core/debugbundle/summary.go b/internal/core/debugbundle/summary.go deleted file mode 100644 index 2b2834b6..00000000 --- a/internal/core/debugbundle/summary.go +++ /dev/null @@ -1,145 +0,0 @@ -package debugbundle - -import ( - "bytes" - "fmt" - "io" - "strings" - "time" - - "gitea.maximumdirect.net/eric/notarius/internal/core/artifacts" - "gitea.maximumdirect.net/eric/notarius/internal/core/fileio" - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" - "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" -) - -const ( - ArtifactInvocationMetadata = "invocation.json" - ArtifactEffectiveConfigYAML = "effective-config.yml" - ArtifactResolvedPipeline = "resolved-pipeline.json" - ArtifactResolvedReferences = "resolved-references.json" - ArtifactCheckpointEvents = "checkpoint-events.json" - ArtifactRunManifest = "run-manifest.json" - ArtifactChunkPlan = "chunk-plan.json" - ArtifactRunReport = "run-report.json" - ArtifactDiagnostics = "final-diagnostics.json" - ArtifactErrorLog = "error.log" -) - -type EffectiveConfigWriter interface{ WriteEffective(io.Writer) error } -type RedactedResolvedPipelinePayload interface { - RedactedResolvedPipelinePayload() pipeline.ResolvedPipeline -} -type Invocation struct { - Operation string `json:"operation"` - PipelineID string `json:"pipeline_id,omitempty"` - PipelineDigest string `json:"pipeline_digest,omitempty"` - Resume bool `json:"resume,omitempty"` - RecomputeStep string `json:"recompute_step,omitempty"` - InputPath string `json:"input_path,omitempty"` - ConfigPath string `json:"config_path,omitempty"` - ConfigSource string `json:"config_source,omitempty"` - ConfigOverlay string `json:"config_overlay,omitempty"` - OnlyLanes []string `json:"only_lanes,omitempty"` - ChunkCacheOverride string `json:"chunk_cache_override,omitempty"` - ReasoningEffortOverride *string `json:"reasoning_effort_override,omitempty"` - SessionID string `json:"session_id,omitempty"` - RunID string `json:"run_id"` - StartedAt time.Time `json:"started_at"` -} -type RunReport struct { - RunID string `json:"run_id"` - PipelineID string `json:"pipeline_id"` - OutputPath string `json:"output_path,omitempty"` - DebugPath string `json:"debug_path,omitempty"` - Succeeded bool `json:"succeeded"` - OutputCount int `json:"output_count"` - RejectedCount int `json:"rejected_count"` - WarningGroupCount int `json:"warning_group_count"` - WarningOccurrenceCount int `json:"warning_occurrence_count"` - DiagnosticGroupCount int `json:"diagnostic_group_count"` - DiagnosticOccurrenceCount int `json:"diagnostic_occurrence_count"` - DiagnosticsTruncated bool `json:"diagnostics_truncated"` - ValidationStatus string `json:"validation_status,omitempty"` -} -type SummaryWriter struct { - root, runID string - createdAt time.Time -} - -func (w *SummaryWriter) WriteInvocation(payload Invocation) error { - if w == nil { - return fmt.Errorf("debug summary writer must not be nil") - } - if payload.RunID == "" { - payload.RunID = w.runID - } - if payload.StartedAt.IsZero() { - payload.StartedAt = w.createdAt - } - if payload.ReasoningEffortOverride != nil { - value := *payload.ReasoningEffortOverride - payload.ReasoningEffortOverride = &value - } - return w.writeJSON(ArtifactInvocationMetadata, payload) -} -func (w *SummaryWriter) WriteEffectiveConfig(payload EffectiveConfigWriter) error { - if payload == nil { - return fmt.Errorf("effective configuration writer must not be nil") - } - var rendered bytes.Buffer - if err := payload.WriteEffective(&rendered); err != nil { - return fmt.Errorf("render effective configuration: %w", err) - } - return w.writeBytes(ArtifactEffectiveConfigYAML, rendered.Bytes()) -} -func (w *SummaryWriter) WriteResolvedPipeline(payload RedactedResolvedPipelinePayload) error { - if payload == nil { - return fmt.Errorf("redacted resolved pipeline payload must not be nil") - } - return w.writeJSON(ArtifactResolvedPipeline, payload.RedactedResolvedPipelinePayload()) -} -func (w *SummaryWriter) WriteResolvedReferences(v []artifacts.ReferenceProvenance) error { - return w.writeJSON(ArtifactResolvedReferences, v) -} -func (w *SummaryWriter) WriteCheckpointEvents(v []pipeline.CheckpointEvent) error { - return w.writeJSON(ArtifactCheckpointEvents, v) -} -func (w *SummaryWriter) WriteRunManifest(v artifacts.RunManifest) error { - return w.writeJSON(ArtifactRunManifest, v) -} -func (w *SummaryWriter) WriteChunkPlan(v artifacts.ChunkPlanSummary) error { - return w.writeJSON(ArtifactChunkPlan, v) -} -func (w *SummaryWriter) WriteRunReport(v RunReport) error { return w.writeJSON(ArtifactRunReport, v) } -func (w *SummaryWriter) WriteDiagnostics(v contracts.DiagnosticCollection) error { - return w.writeJSON(ArtifactDiagnostics, contracts.CloneDiagnosticCollection(v)) -} -func (w *SummaryWriter) WriteError(message string) error { - return w.writeBytes(ArtifactErrorLog, []byte(message+"\n")) -} -func (w *SummaryWriter) writeJSON(name string, v any) error { - if w == nil { - return fmt.Errorf("debug summary writer must not be nil") - } - if err := fileio.WriteJSON(w.root, summaryName(name), v, 0o700, 0o600); err != nil { - return fmt.Errorf("write debug summary artifact %q: %w", name, err) - } - return nil -} -func (w *SummaryWriter) writeBytes(name string, v []byte) error { - if w == nil { - return fmt.Errorf("debug summary writer must not be nil") - } - if err := fileio.WriteBytes(w.root, summaryName(name), v, 0o700, 0o600); err != nil { - return fmt.Errorf("write debug summary artifact %q: %w", name, err) - } - return nil -} -func summaryName(name string) string { - name = strings.TrimSpace(name) - if name == "" || strings.ContainsAny(name, "/\\") { - return "../invalid" - } - return name -} diff --git a/internal/framework/debug/recorder.go b/internal/framework/debug/recorder.go index 4f28bc35..2528e007 100644 --- a/internal/framework/debug/recorder.go +++ b/internal/framework/debug/recorder.go @@ -1,38 +1,167 @@ +// Package debug records explicitly requested application evidence. package debug import ( - "strings" + "errors" + "fmt" + "sync" + "time" + "gitea.maximumdirect.net/eric/notarius/internal/core/debugbundle" "gitea.maximumdirect.net/eric/notarius/internal/core/fileio" - "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" ) -type FilesystemRecorder struct { - root string +// Recorder writes evidence incrementally. It retains only lifecycle information +// and the first recording error, not the pipeline's content. +type Recorder struct { + bundle *debugbundle.Bundle + mu sync.Mutex + recordingErr error + finalized bool + finalErr error } -func NewFilesystemRecorder(root string) (pipeline.DebugRecorder, error) { - root = strings.TrimSpace(root) - if strings.TrimSpace(root) == "" { - return pipeline.NoopDebugRecorder(), nil +func Start(parent, runID string, startedAt time.Time) (*Recorder, error) { + bundle, err := debugbundle.Allocate(parent, runID, startedAt) + if bundle == nil { + return nil, err } - return &FilesystemRecorder{root: root}, nil + recorder := &Recorder{bundle: bundle} + if err != nil { + recorder.RecordError(err) + return recorder, err + } + if err := recorder.WriteJSON("run.json", struct { + RunID string `json:"run_id"` + StartedAt time.Time `json:"started_at"` + }{runID, startedAt}); err != nil { + return recorder, err + } + if err := recorder.WriteBytes("overview.txt", []byte(fmt.Sprintf("Run: %s\nStarted: %s\nCapture: %s\nStatus: running\n", runID, startedAt.Format(time.RFC3339Nano), recorder.Path()))); err != nil { + return recorder, err + } + return recorder, nil } -func (r *FilesystemRecorder) Enabled() bool { - return r != nil && strings.TrimSpace(r.root) != "" +func (r *Recorder) Enabled() bool { return r != nil && r.bundle != nil } +func (r *Recorder) Path() string { + if r == nil { + return "" + } + return r.bundle.Path() } -func (r *FilesystemRecorder) WriteJSON(name string, payload any) error { +// RecordError retains callback failures for a boundary that can return errors. +func (r *Recorder) RecordError(err error) { + if !r.Enabled() || err == nil { + return + } + r.mu.Lock() + defer r.mu.Unlock() + r.remember(err) +} +func (r *Recorder) remember(err error) { + if r.recordingErr == nil { + r.recordingErr = err + } +} +func (r *Recorder) Err() error { if !r.Enabled() { return nil } - return fileio.WriteJSON(r.root, name, payload, 0o700, 0o600) + r.mu.Lock() + defer r.mu.Unlock() + return r.recordingErr } -func (r *FilesystemRecorder) WriteBytes(name string, data []byte) error { +func (r *Recorder) WriteJSON(name string, payload any) error { if !r.Enabled() { return nil } - return fileio.WriteBytes(r.root, name, data, 0o700, 0o600) + r.mu.Lock() + defer r.mu.Unlock() + if r.finalized { + return fmt.Errorf("debug capture %q is finalized", r.Path()) + } + if err := fileio.WriteJSON(r.Path(), name, payload, 0o700, 0o600); err != nil { + r.remember(fmt.Errorf("record debug %q in %q: %w", name, r.Path(), err)) + } + return r.recordingErr +} +func (r *Recorder) WriteBytes(name string, content []byte) error { + if !r.Enabled() { + return nil + } + r.mu.Lock() + defer r.mu.Unlock() + if r.finalized { + return fmt.Errorf("debug capture %q is finalized", r.Path()) + } + if err := fileio.WriteBytes(r.Path(), name, content, 0o700, 0o600); err != nil { + r.remember(fmt.Errorf("record debug %q in %q: %w", name, r.Path(), err)) + } + return r.recordingErr +} + +// Finalize writes one terminal outcome, retaining a primary operation failure +// before additional capture failures. Repeated calls neither write nor retarget +// latest. An additional primary error is preserved alongside the original +// finalization result, including when presentation fails after capture finishes. +func (r *Recorder) Finalize(outcome any, primaryErr error) error { + if !r.Enabled() { + return primaryErr + } + r.mu.Lock() + defer r.mu.Unlock() + if r.finalized { + if primaryErr == nil { + return r.finalErr + } + if errors.Is(primaryErr, r.finalErr) { + return primaryErr + } + return errors.Join(primaryErr, r.finalErr) + } + r.finalized = true + completedAt := time.Now().UTC() + terminal := struct { + CompletedAt time.Time `json:"completed_at"` + Outcome any `json:"outcome,omitempty"` + Error string `json:"error,omitempty"` + CaptureError string `json:"capture_error,omitempty"` + }{CompletedAt: completedAt, Outcome: outcome} + if primaryErr != nil { + terminal.Error = primaryErr.Error() + } + if r.recordingErr != nil { + terminal.CaptureError = r.recordingErr.Error() + } + outcomeErr := fileio.WriteJSON(r.Path(), "outcome.json", terminal, 0o700, 0o600) + if outcomeErr != nil { + outcomeErr = fmt.Errorf("finalize debug outcome in %q: %w", r.Path(), outcomeErr) + } + status := "completed" + if primaryErr != nil || r.recordingErr != nil || outcomeErr != nil { + status = "failed" + } + overview := fmt.Sprintf("Run: %s\nStarted: %s\nCompleted: %s\nCapture: %s\nStatus: %s\n", r.bundle.RunID(), r.bundle.CreatedAt().Format(time.RFC3339Nano), completedAt.Format(time.RFC3339Nano), r.Path(), status) + if primaryErr != nil { + overview += "Error: " + primaryErr.Error() + "\n" + } + if r.recordingErr != nil { + overview += "Capture error: " + r.recordingErr.Error() + "\n" + } + if outcomeErr != nil { + overview += "Capture error: " + outcomeErr.Error() + "\n" + } + overviewErr := fileio.WriteBytes(r.Path(), "overview.txt", []byte(overview), 0o700, 0o600) + if overviewErr != nil { + overviewErr = fmt.Errorf("finalize debug overview in %q: %w", r.Path(), overviewErr) + } + captureErr := r.recordingErr + if primaryErr != nil && errors.Is(primaryErr, captureErr) { + captureErr = nil + } + r.finalErr = errors.Join(primaryErr, captureErr, outcomeErr, overviewErr) + return r.finalErr } diff --git a/internal/framework/debug/recorder_test.go b/internal/framework/debug/recorder_test.go index 167df4e7..8fb89172 100644 --- a/internal/framework/debug/recorder_test.go +++ b/internal/framework/debug/recorder_test.go @@ -1,79 +1,210 @@ package debug import ( + "encoding/json" + "errors" "fmt" "os" "path/filepath" + "strings" "sync" "testing" + "time" "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" ) -func TestFilesystemRecorderWritesWithinTraceRoot(t *testing.T) { - root := t.TempDir() - recorder, err := NewFilesystemRecorder(root) +func startTestCapture(t *testing.T, parent, id string) *Recorder { + t.Helper() + recorder, err := Start(parent, id, time.Unix(42, 0).UTC()) if err != nil { t.Fatal(err) } - if err := recorder.WriteBytes("attempt/data", []byte("payload")); err != nil { + return recorder +} + +func TestRecorderPersistsIncrementallyAndFinalizesOnce(t *testing.T) { + parent := t.TempDir() + recorder := startTestCapture(t, parent, "first") + var _ pipeline.DebugRecorder = recorder + source := strings.Repeat("Source text and sk-ordinary-application-content. ", 400) + if err := recorder.WriteBytes("operations/extract/source.txt", []byte(source)); err != nil { t.Fatal(err) } - info, err := os.Stat(filepath.Join(root, "attempt", "data")) - if err != nil { + if got, err := os.ReadFile(filepath.Join(recorder.Path(), "operations/extract/source.txt")); err != nil || string(got) != source { + t.Fatalf("incremental evidence=%q %v", got, err) + } + second := startTestCapture(t, parent, "second") + primary := errors.New("pipeline failed") + result := struct { + OutputDirectory string + Published bool + }{"/output/already-published", true} + if err := recorder.Finalize(result, primary); !errors.Is(err, primary) { + t.Fatalf("primary failure lost: %v", err) + } + before, err := os.ReadFile(filepath.Join(recorder.Path(), "outcome.json")) + if err != nil || !strings.Contains(string(before), result.OutputDirectory) || !strings.Contains(string(before), primary.Error()) { + t.Fatalf("terminal evidence=%s %v", before, err) + } + if err := recorder.Finalize("replacement", nil); !errors.Is(err, primary) { + t.Fatalf("repeat finalization=%v", err) + } + after, err := os.ReadFile(filepath.Join(recorder.Path(), "outcome.json")) + if err != nil || string(after) != string(before) { + t.Fatalf("terminal outcome rewritten: %q %v", after, err) + } + if err := second.Finalize(map[string]any{"success": true}, nil); err != nil { t.Fatal(err) } - if info.Mode().Perm() != 0o600 { - t.Fatalf("mode=%#o", info.Mode().Perm()) + deliveryErr := errors.New("stdout delivery failed after publication") + if err := second.Finalize(nil, deliveryErr); !errors.Is(err, deliveryErr) { + t.Fatalf("post-capture delivery failure lost: %v", err) } - if err := recorder.WriteBytes("../outside", nil); err == nil { - t.Fatal("accepted traversal") + target, err := os.Readlink(filepath.Join(parent, "latest")) + if err != nil || target != "second" { + t.Fatalf("completion retargeted latest: %q %v", target, err) + } + if err := recorder.WriteBytes("late.txt", nil); err == nil { + t.Fatal("write after finalization succeeded") + } + info, err := os.Stat(filepath.Join(recorder.Path(), "outcome.json")) + if err != nil || info.Mode().Perm() != 0o600 { + t.Fatalf("capture file=%v %v", info, err) } } -func TestFilesystemRecorderPropagatesWriteFailures(t *testing.T) { - root := filepath.Join(t.TempDir(), "trace") - if err := os.WriteFile(root, []byte("not a directory"), 0o600); err != nil { +func TestRecorderRetainsCallbackErrorAndExposesItAtBoundary(t *testing.T) { + recorder := startTestCapture(t, t.TempDir(), "run") + callbackErr := errors.New("observer recording failed") + recorder.RecordError(callbackErr) + if !errors.Is(recorder.Err(), callbackErr) { + t.Fatal("callback failure not retained") + } + if err := recorder.WriteJSON("available.json", map[string]string{"available": "evidence"}); !errors.Is(err, callbackErr) { + t.Fatalf("boundary hid callback error: %v", err) + } + if _, err := os.Stat(filepath.Join(recorder.Path(), "available.json")); err != nil { t.Fatal(err) } - recorder, err := NewFilesystemRecorder(root) - if err != nil { - t.Fatal(err) - } - if err := recorder.WriteBytes("attempt/data", []byte("payload")); err == nil { - t.Fatal("WriteBytes concealed a trace-root write failure") + primary := errors.New("primary operation failed") + err := recorder.Finalize(map[string]string{"output_directory": "/published"}, primary) + if !errors.Is(err, primary) || !errors.Is(err, callbackErr) || !strings.HasPrefix(err.Error(), primary.Error()) { + t.Fatalf("failure causes/order lost: %v", err) } } -func TestSynchronizedFilesystemRecorderSupportsConcurrentWrites(t *testing.T) { +func TestRecorderWriteAndFinalizationFailuresPreserveEvidence(t *testing.T) { + for _, defect := range []string{"incremental write", "outcome write", "overview write", "outcome encoding"} { + t.Run(defect, func(t *testing.T) { + recorder := startTestCapture(t, t.TempDir(), "run") + if err := recorder.WriteBytes("available.txt", []byte("retained")); err != nil { + t.Fatal(err) + } + var result any = map[string]any{"output_directory": "/published", "artifact_count": 2} + switch defect { + case "incremental write": + if err := os.WriteFile(filepath.Join(recorder.Path(), "operations"), nil, 0o600); err != nil { + t.Fatal(err) + } + if err := recorder.WriteJSON("operations/result.json", result); err == nil { + t.Fatal("write failure hidden") + } + case "outcome write": + if err := os.Mkdir(filepath.Join(recorder.Path(), "outcome.json"), 0o700); err != nil { + t.Fatal(err) + } + case "overview write": + // Replace only the initial overview file with a directory to make the + // terminal write fail, without relying on effective UID permissions. + filename := filepath.Join(recorder.Path(), "overview.txt") + if err := os.Rename(filename, filepath.Join(recorder.Path(), "initial-overview.txt")); err != nil { + t.Fatal(err) + } + if err := os.Mkdir(filename, 0o700); err != nil { + t.Fatal(err) + } + case "outcome encoding": + result = make(chan int) + } + finalErr := recorder.Finalize(result, nil) + if finalErr == nil { + t.Fatal("capture failure reported success") + } + if got, err := os.ReadFile(filepath.Join(recorder.Path(), "available.txt")); err != nil || string(got) != "retained" { + t.Fatalf("evidence removed: %q %v", got, err) + } + primary := errors.New("new failure") + if err := recorder.Finalize(nil, primary); !errors.Is(err, primary) || !errors.Is(err, finalErr) { + t.Fatalf("additional primary error or original capture failure lost: %v", err) + } + }) + } +} + +func TestRecorderStartFailureProvidesAvailableDirectory(t *testing.T) { root := t.TempDir() - recorder, err := NewFilesystemRecorder(root) - if err != nil { + if err := os.Mkdir(filepath.Join(root, "latest"), 0o700); err != nil { t.Fatal(err) } - recorder = pipeline.SynchronizedDebugRecorder(recorder) + recorder, err := Start(root, "run", time.Now()) + if err == nil || recorder == nil || recorder.Path() != filepath.Join(root, "run") { + t.Fatalf("start=%#v %v", recorder, err) + } + if err := recorder.Finalize(nil, err); err == nil { + t.Fatal("start failure concealed") + } + if _, err := os.Stat(filepath.Join(recorder.Path(), "outcome.json")); err != nil { + t.Fatal(err) + } +} - const writes = 16 +func TestRecorderConcurrentWritesAndBoundaryChecks(t *testing.T) { + recorder := startTestCapture(t, t.TempDir(), "run") + const count = 16 var wg sync.WaitGroup - errs := make(chan error, writes) - for i := 0; i < writes; i++ { - i := i + failures := make(chan error, count) + for i := range count { wg.Add(1) - go func() { + go func(i int) { defer wg.Done() - errs <- recorder.WriteBytes(fmt.Sprintf("attempt/%02d/data", i), []byte("payload")) - }() + failures <- recorder.WriteJSON(fmt.Sprintf("operations/%02d/result.json", i), map[string]int{"value": i}) + _ = recorder.Err() + }(i) } wg.Wait() - close(errs) - for err := range errs { + close(failures) + for err := range failures { if err != nil { t.Fatal(err) } } - for i := 0; i < writes; i++ { - if _, err := os.Stat(filepath.Join(root, "attempt", fmt.Sprintf("%02d", i), "data")); err != nil { - t.Fatalf("trace artifact %d: %v", i, err) + if err := recorder.Finalize(map[string]int{"operations": count}, nil); err != nil { + t.Fatal(err) + } + for i := range count { + content, err := os.ReadFile(filepath.Join(recorder.Path(), fmt.Sprintf("operations/%02d/result.json", i))) + var decoded map[string]int + if err != nil || json.Unmarshal(content, &decoded) != nil || decoded["value"] != i { + t.Fatalf("operation %d: %s %v", i, content, err) } } } + +func TestDisabledRecorderIsANoopAndPreservesPrimaryFailure(t *testing.T) { + var recorder *Recorder + primary := errors.New("operation failed") + if recorder.Enabled() || recorder.Path() != "" || recorder.Err() != nil { + t.Fatal("nil recorder enabled") + } + if err := recorder.WriteJSON("../ignored", make(chan int)); err != nil { + t.Fatal(err) + } + if err := recorder.WriteBytes("../ignored", nil); err != nil { + t.Fatal(err) + } + recorder.RecordError(errors.New("ignored")) + if err := recorder.Finalize(nil, primary); err != primary { + t.Fatalf("primary=%v", err) + } +}