2026-09-07 03:54:41 +00:00
package config
import (
"bytes"
"errors"
"fmt"
2026-11-17 22:09:58 +00:00
"os"
2026-09-07 03:54:41 +00:00
"path/filepath"
"reflect"
"strings"
2026-11-17 21:59:19 +00:00
configkit "go.maximumdirect.net/configkit"
2026-09-07 03:54:41 +00:00
)
type pipelineResolutionMetadata struct {
rootPath string
imports [ ] string
sources [ ] string
2026-09-25 15:24:03 +00:00
selectedOverlay * pipelineOverlaySelection
2026-09-07 03:54:41 +00:00
effectiveDigest string
artifactFamilies map [ string ] ScriptoriumArtifactFamilyConfig
artifactFamiliesExpanded bool
configkitMetadata configkit . Metadata
configkitSources [ ] configkit . SourceInfo
2026-11-17 22:31:03 +00:00
inspection * configkit . Result [ effectivePipelineProjection ]
2026-11-17 22:35:56 +00:00
authoring * configkit . Result [ PipelineConfig ]
2026-09-07 03:54:41 +00:00
}
2026-09-25 15:24:03 +00:00
type pipelineOverlaySelection struct {
2026-09-07 03:54:41 +00:00
name string
source string
overlayPath string
}
func loadPipelineWithConfigKit ( path string , opts PipelineLoadOptions ) ( * PipelineConfig , error ) {
2026-09-25 15:24:03 +00:00
overlay := selectedPipelineOverlayName ( opts )
2026-11-17 22:06:29 +00:00
source := configkit . File ( strings . TrimSpace ( path ) )
if strings . TrimSpace ( path ) == "" {
search := configkit . Searches ( configkit . WorkingDirectory ( ) , configkit . UserConfigDirectory ( ) , configkit . UnixSystemDirectories ( ) )
if opts . Search != nil {
search = * opts . Search
}
source = configkit . SearchConfig ( "narratio" , search , configkit . SearchOptions { Required : true } )
}
result , err := loadPipelineConfigKitResult ( source , overlay )
2026-09-07 03:54:41 +00:00
if err != nil {
return nil , describePipelineLoadError ( err )
}
cfg := result . Config
2026-10-04 13:34:27 +00:00
cfg . resolution = pipelineMetadataFromConfigKit ( result , opts )
2026-09-07 03:54:41 +00:00
return & cfg , nil
}
2026-11-17 22:06:29 +00:00
func loadPipelineConfigKitResult ( source configkit . Source , overlay string ) ( * configkit . Result [ PipelineConfig ] , error ) {
2026-11-17 22:09:58 +00:00
invocationDir , err := os . Getwd ( )
if err != nil {
return nil , fmt . Errorf ( "capture invocation directory: %w" , err )
}
2026-11-17 22:06:29 +00:00
return configkit . Load ( source , configkit . Options [ PipelineConfig ] {
2026-09-07 11:59:49 +00:00
Imports : true ,
2026-09-25 15:24:03 +00:00
Overlay : overlay ,
2026-09-07 11:59:49 +00:00
Definition : configkit . Definition [ PipelineConfig ] {
Defaults : pipelineConfigDefaults ,
2026-11-17 22:09:58 +00:00
Resolve : func ( cfg * PipelineConfig , resolution * configkit . Resolution ) error {
return resolvePipelineConfig ( cfg , resolution , invocationDir )
} ,
2026-09-07 11:59:49 +00:00
Validate : validatePipelineConfigKit ,
} ,
} )
}
2026-09-07 03:54:41 +00:00
func describePipelineLoadError ( err error ) error {
2026-09-07 04:02:21 +00:00
return describeConfigKitLoadError ( "pipeline" , err )
}
func describeConfigKitLoadError ( kind string , err error ) error {
2026-09-07 03:54:41 +00:00
var loadError * configkit . LoadError
if ! errors . As ( err , & loadError ) {
2026-09-07 04:02:21 +00:00
return fmt . Errorf ( "load %s config: %w" , kind , err )
2026-09-07 03:54:41 +00:00
}
var diagnostics bytes . Buffer
resolved := loadError . Diagnostics ( )
sourcePaths := make ( map [ string ] string , len ( loadError . Sources ( ) ) )
for _ , source := range loadError . Sources ( ) {
if source . Path != "" {
sourcePaths [ source . ID ] = source . Path
} else if source . Label != "" {
sourcePaths [ source . ID ] = source . Label
}
}
for index := range resolved {
if resolved [ index ] . Primary != nil {
if name := sourcePaths [ resolved [ index ] . Primary . SourceID ] ; name != "" {
resolved [ index ] . Primary . SourceID = name
}
}
for relatedIndex := range resolved [ index ] . Related {
if name := sourcePaths [ resolved [ index ] . Related [ relatedIndex ] . SourceID ] ; name != "" {
resolved [ index ] . Related [ relatedIndex ] . SourceID = name
}
}
}
if writeErr := configkit . WriteDiagnostics ( & diagnostics , resolved ) ; writeErr != nil {
2026-09-07 04:02:21 +00:00
return fmt . Errorf ( "load %s config: %w" , kind , err )
2026-09-07 03:54:41 +00:00
}
2026-09-07 04:02:21 +00:00
return fmt . Errorf ( "load %s config: strict decode failed or validation failed: %w: %s" , kind , err , strings . TrimSpace ( diagnostics . String ( ) ) )
2026-09-07 03:54:41 +00:00
}
2026-09-25 15:24:03 +00:00
func selectedPipelineOverlayName ( opts PipelineLoadOptions ) string {
if opts . Overlay == nil || * opts . Overlay == "" || * opts . Overlay == "default" {
2026-09-07 03:54:41 +00:00
return ""
}
2026-09-25 15:24:03 +00:00
return * opts . Overlay
2026-09-07 03:54:41 +00:00
}
func pipelineConfigDefaults ( ) PipelineConfig {
return PipelineConfig {
Workspace : WorkspaceConfig { Root : DefaultWorkspaceRoot } ,
Campaigns : CampaignsConfig { Root : DefaultCampaignsRoot } ,
Storage : StorageConfig { Backend : StorageBackendLocal } ,
Spool : SpoolConfig { Root : DefaultSpoolRoot } ,
Cache : CacheConfig { Root : DefaultCacheRoot , S3Audio : boolPtr ( DefaultCacheS3Audio ) } ,
Publish : & PublishConfig {
Enabled : boolPtr ( DefaultArchiveEnabled ) , UploadRun : boolPtr ( DefaultArchiveUploadRun ) ,
Outputs : defaultPublishOutputs ( ) ,
} ,
WhisperX : WhisperXConfig {
Language : DefaultWhisperXLanguage , Timeout : DefaultWhisperXTimeout ,
RetryDelay : DefaultWhisperXRetryDelay , Concurrency : intPtr ( DefaultWhisperXConcurrency ) ,
Retries : intPtr ( DefaultWhisperXRetries ) ,
} ,
Seriatim : SeriatimConfig {
Binary : DefaultSeriatimBinary , Timeout : DefaultSeriatimTimeout ,
OutputSchema : DefaultSeriatimOutputSchema , CoalesceGap : float64Ptr ( DefaultSeriatimCoalesceGap ) ,
Report : boolPtr ( DefaultSeriatimReport ) ,
} ,
2026-09-25 15:45:02 +00:00
Audita : AuditaConfig { Binary : DefaultAuditaBinary , Timeout : DefaultAuditaTimeout } ,
2026-09-07 03:54:41 +00:00
Normalize : & NormalizeConfig { OutputPath : DefaultNormalizeOutputPath , OutputSchema : DefaultNormalizeOutputSchema , Report : boolPtr ( DefaultNormalizeReport ) } ,
Trim : & TrimConfig {
Enabled : boolPtr ( DefaultTrimEnabled ) , OutputPath : DefaultTrimOutputPath ,
Bounds : TrimBoundsConfig {
PromptID : DefaultTrimBoundsPromptID , TranscriptInputName : DefaultTrimBoundsTranscriptInputName ,
OutputPath : DefaultTrimBoundsOutputPath , Timeout : DefaultTrimBoundsTimeout ,
} ,
Seriatim : TrimSeriatimConfig { Report : boolPtr ( DefaultTrimSeriatimReport ) } ,
} ,
Render : & RenderConfig {
Enabled : boolPtr ( DefaultRenderEnabled ) , Format : DefaultRenderFormat , Title : DefaultRenderTitle ,
IncludeTimestamps : boolPtr ( DefaultRenderTimestamps ) , IncludeSegmentIDs : boolPtr ( DefaultRenderSegmentIDs ) ,
} ,
Notification : NotificationConfig { Mode : DefaultNotificationMode } ,
}
}
func defaultPublishOutputs ( ) [ ] PublishOutputRule {
outputs := append ( [ ] PublishOutputRule ( nil ) , DefaultPublishOutputs ... )
for index := range outputs {
outputs [ index ] . Required = boolPtr ( true )
}
return outputs
}
2026-11-17 22:09:58 +00:00
func resolvePipelineConfig ( cfg * PipelineConfig , resolution * configkit . Resolution , invocationDir string ) error {
resolveHostResource ( resolution , configkit . Keys ( "workspace" , "root" ) , & cfg . Workspace . Root , invocationDir )
resolveHostResource ( resolution , configkit . Keys ( "campaigns" , "root" ) , & cfg . Campaigns . Root , invocationDir )
resolveHostResource ( resolution , configkit . Keys ( "spool" , "root" ) , & cfg . Spool . Root , invocationDir )
resolveHostResource ( resolution , configkit . Keys ( "cache" , "root" ) , & cfg . Cache . Root , invocationDir )
resolveHostResource ( resolution , configkit . Keys ( "audita" , "config_path" ) , & cfg . Audita . ConfigPath , invocationDir )
if cfg . Scriptorium != nil {
resolveHostResource ( resolution , configkit . Keys ( "scriptorium" , "config_path" ) , & cfg . Scriptorium . ConfigPath , invocationDir )
}
if cfg . Notarius != nil {
resolveHostResource ( resolution , configkit . Keys ( "notarius" , "config_path" ) , & cfg . Notarius . ConfigPath , invocationDir )
resolveHostResource ( resolution , configkit . Keys ( "notarius" , "working_directory" ) , & cfg . Notarius . WorkingDirectory , invocationDir )
}
2026-09-07 03:54:41 +00:00
backend := strings . ToLower ( strings . TrimSpace ( cfg . Storage . Backend ) )
if backend != cfg . Storage . Backend {
configkit . Normalize ( resolution , configkit . Keys ( "storage" , "backend" ) , & cfg . Storage . Backend , backend , "canonical storage backend" )
}
if cfg . Storage . S3 != nil {
path := configkit . Keys ( "storage" , "s3" )
configkit . Default ( resolution , path . Key ( "root_prefix" ) , & cfg . Storage . S3 . RootPrefix , DefaultStorageS3RootPrefix , "default S3 root prefix" )
}
if cfg . Trim != nil && cfg . Trim . Enabled != nil && * cfg . Trim . Enabled && cfg . Scriptorium == nil {
value := & ScriptoriumConfig { Binary : DefaultScriptoriumBinary , Timeout : DefaultScriptoriumTimeout }
configkit . Default ( resolution , configkit . Keys ( "scriptorium" ) , & cfg . Scriptorium , value , "trim requires Scriptorium" )
}
if cfg . Scriptorium != nil {
path := configkit . Keys ( "scriptorium" )
configkit . Default ( resolution , path . Key ( "binary" ) , & cfg . Scriptorium . Binary , DefaultScriptoriumBinary , "default Scriptorium binary" )
configkit . Default ( resolution , path . Key ( "timeout" ) , & cfg . Scriptorium . Timeout , DefaultScriptoriumTimeout , "default Scriptorium timeout" )
}
if cfg . Notarius != nil {
path := configkit . Keys ( "notarius" )
configkit . Default ( resolution , path . Key ( "binary" ) , & cfg . Notarius . Binary , DefaultNotariusBinary , "default Notarius binary" )
configkit . Default ( resolution , path . Key ( "timeout" ) , & cfg . Notarius . Timeout , DefaultNotariusTimeout , "default Notarius timeout" )
if cfg . Notarius . Enabled && cfg . Notarius . ConfigPath != "" {
configkit . Default ( resolution , path . Key ( "working_directory" ) , & cfg . Notarius . WorkingDirectory ,
filepath . Dir ( cfg . Notarius . ConfigPath ) , "derived from Notarius config path" , path . Key ( "config_path" ) )
}
}
if cfg . Publish != nil {
defaultedOutput := false
for index := range cfg . Publish . Outputs {
output := cfg . Publish . Outputs [ index ]
path := configkit . Keys ( "publish" , "outputs" ) . Index ( index ) . Key ( "required" )
if ! resolution . IsExplicit ( path ) {
defaultedOutput = true
}
configkit . Default ( resolution , path , & output . Required , boolPtr ( true ) , "publish outputs are required by default" )
cfg . Publish . Outputs [ index ] = output
}
if defaultedOutput {
2026-11-17 21:59:19 +00:00
resolution . RecordDerivedDefault ( configkit . Keys ( "publish" , "outputs" ) , "publish output entry defaults" )
2026-09-07 03:54:41 +00:00
}
}
before := cloneNotariusForResolution ( cfg . Notarius )
if err := NormalizePipelineConfig ( cfg ) ; err != nil {
resolution . Error ( configkit . Keys ( "notarius" ) , err . Error ( ) )
return nil
}
if ! reflect . DeepEqual ( before , cfg . Notarius ) {
2026-11-17 21:59:19 +00:00
resolution . RecordNormalization ( configkit . Keys ( "notarius" ) , "canonical Notarius configuration" )
2026-09-07 03:54:41 +00:00
}
if cfg . Publish != nil {
2026-09-21 03:06:13 +00:00
destinations := deriveMissingPublishDestinations ( cfg . Publish , cfg . Scriptorium , cfg . Notarius )
for _ , derived := range destinations {
2026-09-07 11:52:57 +00:00
output := cfg . Publish . Outputs [ derived . index ]
configkit . Normalize ( resolution , configkit . Keys ( "publish" , "outputs" ) . Index ( derived . index ) . Key ( "dest" ) , & output . Dest , derived . dest , "derived from publish source" )
cfg . Publish . Outputs [ derived . index ] = output
2026-09-07 03:54:41 +00:00
}
2026-09-21 03:06:13 +00:00
if len ( destinations ) > 0 {
// ConfigKit compares sequences atomically; child records alone do not
// cover the list mutation when requiredness was already explicit.
2026-11-17 21:59:19 +00:00
resolution . RecordNormalization ( configkit . Keys ( "publish" , "outputs" ) , "derived publish destinations" )
2026-09-21 03:06:13 +00:00
}
2026-09-07 03:54:41 +00:00
}
return nil
}
func cloneNotariusForResolution ( value * NotariusConfig ) * NotariusConfig {
if value == nil {
return nil
}
clone := * value
clone . References = cloneStringMap ( value . References )
if value . Outputs != nil {
clone . Outputs = make ( map [ string ] NotariusOutputConfig , len ( value . Outputs ) )
for key , output := range value . Outputs {
clone . Outputs [ key ] = output
}
}
return & clone
}
func cloneStringMap ( value map [ string ] string ) map [ string ] string {
if value == nil {
return nil
}
clone := make ( map [ string ] string , len ( value ) )
for key , item := range value {
clone [ key ] = item
}
return clone
}
func validatePipelineConfigKit ( cfg * PipelineConfig , validation * configkit . Validation ) {
// Checks that depend on family expansion or campaign/session context remain
// at Narratio's explicit resolution boundary. This early definition check is
// deliberately limited to an invariant that is wholly file-local.
if strings . TrimSpace ( cfg . Workspace . Root ) == "" {
validation . Error ( configkit . Keys ( "workspace" , "root" ) , "workspace root is required" )
}
}
2026-10-04 13:34:27 +00:00
func pipelineMetadataFromConfigKit ( result * configkit . Result [ PipelineConfig ] , opts PipelineLoadOptions ) * pipelineResolutionMetadata {
2026-09-07 03:54:41 +00:00
sources := result . Sources ( )
resolved := & pipelineResolutionMetadata {
2026-11-17 22:35:56 +00:00
configkitMetadata : result . Metadata ( ) , configkitSources : sources , authoring : result ,
2026-09-07 03:54:41 +00:00
}
for index , source := range sources {
path := source . Path
if path == "" {
path = source . Label
}
resolved . sources = append ( resolved . sources , path )
if index == 0 {
resolved . rootPath = path
2026-11-17 21:59:19 +00:00
} else if source . Layer == configkit . LayerMain {
2026-09-07 03:54:41 +00:00
resolved . imports = append ( resolved . imports , path )
}
2026-09-25 15:24:03 +00:00
if source . Layer == configkit . LayerOverlay {
resolved . selectedOverlay = & pipelineOverlaySelection { name : selectedPipelineOverlayName ( opts ) , source : "explicit" , overlayPath : path }
2026-09-07 03:54:41 +00:00
}
}
2026-10-04 13:34:27 +00:00
return resolved
2026-09-07 03:54:41 +00:00
}
func pipelineMetadataPaths ( cfg * PipelineConfig ) ( [ ] projectedPipelineValue , error ) {
2026-11-17 22:09:58 +00:00
effective , err := projectionDetailedRecords ( projectEffectivePipeline ( cfg ) )
2026-09-07 03:54:41 +00:00
if err != nil {
return nil , err
}
2026-10-04 13:34:27 +00:00
if cfg . Scriptorium == nil {
return effective , nil
}
families := cfg . Scriptorium . ArtifactFamilies
if cfg . resolution != nil && len ( cfg . resolution . artifactFamilies ) != 0 {
families = cfg . resolution . artifactFamilies
}
if len ( families ) == 0 {
2026-09-07 03:54:41 +00:00
return effective , nil
}
2026-10-04 13:34:27 +00:00
detailedFamilies , err := projectionDetailedRecords ( map [ string ] any { "scriptorium" : map [ string ] any { "artifact_families" : families } } )
2026-09-07 03:54:41 +00:00
if err != nil {
return nil , err
}
2026-10-04 13:34:27 +00:00
return append ( effective , detailedFamilies ... ) , nil
2026-09-07 03:54:41 +00:00
}
func ownershipSources ( origin configkit . Origin , pathsByID map [ string ] string ) [ ] string {
if origin . Layer == configkit . LayerDefault || ( origin . Layer == configkit . LayerResolution && origin . Operation == configkit . ChangeDerivedDefault ) {
return [ ] string { pipelineDefaultOwnershipSource }
}
if origin . Layer == configkit . LayerResolution {
return [ ] string { "resolution" }
}
seen := map [ string ] struct { } { }
var sources [ ] string
2026-10-04 13:34:27 +00:00
add := func ( location configkit . Location ) {
2026-09-07 03:54:41 +00:00
value := pathsByID [ location . SourceID ]
if value == "" {
value = location . SourceID
}
if _ , ok := seen [ value ] ; ! ok {
seen [ value ] = struct { } { }
sources = append ( sources , value )
}
}
2026-10-04 13:34:27 +00:00
for _ , location := range origin . Locations {
add ( location )
}
for _ , inheritance := range origin . Inheritance {
for _ , location := range inheritance . Locations {
add ( location )
}
}
2026-09-07 03:54:41 +00:00
if len ( sources ) == 0 {
return [ ] string { pipelineDefaultOwnershipSource }
}
return sources
}
2026-10-04 13:34:27 +00:00
func pipelineSourcePaths ( cfg * PipelineConfig ) map [ string ] string {
paths := make ( map [ string ] string )
if cfg == nil || cfg . resolution == nil {
return paths
}
for _ , source := range cfg . resolution . configkitSources {
2026-11-17 22:35:56 +00:00
if cfg . resolution . authoring != nil {
if found , ok := cfg . resolution . authoring . Source ( source . ID ) ; ok {
source = found
}
}
2026-10-04 13:34:27 +00:00
path := source . Path
if path == "" {
path = source . Label
}
paths [ source . ID ] = path
}
return paths
}
2026-09-07 03:54:41 +00:00
func intPtr ( value int ) * int { return & value }
func float64Ptr ( value float64 ) * float64 { return & value }
func boolPtr ( value bool ) * bool { return & value }