Record debug evidence in one run-scoped capture session

This commit is contained in:
2026-11-22 02:49:48 +00:00
parent 584b041e57
commit 8680060400
10 changed files with 700 additions and 676 deletions

View File

@@ -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`,

View File

@@ -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
}

51
internal/cli/run_debug.go Normal file
View File

@@ -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)
}

View File

@@ -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)
}
}

View File

@@ -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
}

View File

@@ -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}
}

View File

@@ -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"}
}

View File

@@ -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
}

View File

@@ -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
}

View File

@@ -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)
}
}