narratio/internal/adapters/notarius/runner.go

// Package notarius declares the adapter contract for Notarius CLI invocations.
package notarius

import (
	"context"
	"time"
)

const ReceiptSchemaVersion = "notarius.run-result.v2"

// Runner is the adapter boundary for a complete Notarius pipeline invocation.
type Runner interface {
	Run(ctx context.Context, req RunRequest) (RunResult, error)
}

// ReferenceBinding maps one normalized Notarius selector to an absolute
// external reference path.
type ReferenceBinding struct {
	Selector string
	Path     string
}

// RunRequest contains the resolved inputs and diagnostic destinations for one invocation.
type RunRequest struct {
	Binary           string
	ConfigPath       string
	PipelineID       string
	InputPath        string
	OutputRoot       string
	WorkingDirectory string
	ReceiptPath      string
	LogPath          string
	Timeout          time.Duration
	References       []ReferenceBinding
}

// Receipt is the transport-neutral successful run receipt.
type Receipt struct {
	SchemaVersion             string
	RunID                     string
	PipelineID                string
	OutputDirectory           string
	IndexFile                 string
	NormalizedOutputCount     int
	RejectedOutputCount       int
	WarningGroupCount         int
	WarningOccurrenceCount    int
	DiagnosticGroupCount      int
	DiagnosticOccurrenceCount int
	DiagnosticsTruncated      bool
	ValidationStatus          string
	ValidationSummaries       []ValidationSummary
	DebugDirectory            string
}

// ValidationSummary retains the bounded outcome of one Notarius producer result.
type ValidationSummary struct {
	Stage                string
	StepID               string
	LaneID               string
	ModuleKey            string
	ChunkID              string
	Status               string
	RejectingValidators  []string
	ReasonCodes          []string
	IncompleteValidators []string
	ProducerAttemptCount int
	TerminalAction       string
}

// LaneDescriptor identifies one normalized lane payload discovered through the index.
type LaneDescriptor struct {
	LaneID        string
	File          string
	Path          string
	MediaType     string
	ModuleKey     string
	SchemaID      string
	SchemaName    string
	SchemaVersion string
}

// PipelineDescriptor identifies a pipeline-wide artifact discovered through the index.
type PipelineDescriptor struct {
	ArtifactKind  string
	File          string
	Path          string
	MediaType     string
	SchemaID      string
	SchemaName    string
	SchemaVersion string
}

// Index describes the validated bundle-management and artifact paths.
type Index struct {
	Path            string
	ManifestFile    string
	ManifestPath    string
	RejectedFile    string
	RejectedPath    string
	WarningsFile    string
	WarningsPath    string
	DiagnosticsFile string
	DiagnosticsPath string
	Lanes           []LaneDescriptor
	ChunkMap        *PipelineDescriptor
	EvidenceContext *PipelineDescriptor
}

// RejectionSummary retains structured rejection identity without free-form messages.
type RejectionSummary struct {
	Stage         string
	StepID        string
	LaneID        string
	ModuleKey     string
	ChunkID       string
	ValidatorName string
	ReasonCode    string
}

// WarningSummary retains structured warning identity without free-form messages.
type WarningSummary struct {
	Disposition     string
	Category        string
	ReasonCode      string
	Origin          DiagnosticOrigin
	OccurrenceCount int
}

// DiagnosticOrigin identifies the framework-owned pipeline location of a finding.
type DiagnosticOrigin struct {
	Stage        string
	StepID       string
	LaneID       string
	ModuleKey    string
	ValidatorKey string
}

// DiagnosticSummary retains bounded advisory or observation group metadata.
type DiagnosticSummary struct {
	Disposition     string
	Category        string
	ReasonCode      string
	Origin          DiagnosticOrigin
	OccurrenceCount int
}

// RunResult describes a successfully decoded and validated Notarius bundle.
type RunResult struct {
	Receipt     Receipt
	Index       Index
	BundleRoot  string
	ReceiptPath string
	LogPath     string
	ExitCode    int
	Duration    time.Duration
	Rejections  []RejectionSummary
	Warnings    []WarningSummary
	Diagnostics []DiagnosticSummary
}