Expose source version modes in load options

lifecycle.go

@@ -17,15 +17,39 @@ type Definition[T any] struct {
 	Secret   func(Path) bool
 }
 
+// SourceVersionMode controls schema-version declarations across one complete
+// load. The zero value preserves the existing effective-path version check.
+type SourceVersionMode uint8
+
+const (
+	// SourceVersionModeDefault preserves the existing main-version check and
+	// rejects version-path contributions from imported, underlay, and overlay
+	// payloads.
+	SourceVersionModeDefault SourceVersionMode = iota
+	// SourceVersionModeIfPresent checks each participating document that has a
+	// declaration. A missing main declaration still reaches the checker; an
+	// absent non-main declaration skips it. Accepted non-main declarations are
+	// consumed before composition.
+	SourceVersionModeIfPresent
+	// SourceVersionModeRequired requires a declaration in each participating
+	// document. NoSource retains the existing absent-main checker behavior.
+	// Accepted non-main declarations are consumed before composition.
+	SourceVersionModeRequired
+)
+
 // Options contains the application definition and per-load input selections.
 // Imports enables explicit path and glob imports; Overlay selects one fixed overlay;
 // Overrides contains only values explicitly supplied by an application CLI.
+// Enabled source-version modes interpret Definition.Version.Path in each
+// document's local coordinates. Main protection remains at that path prefixed
+// by the main input's Destination.
 type Options[T any] struct {
-	Definition Definition[T]
-	Imports    bool
-	Overlay    string
-	Filesystem *FilesystemContext
-	Overrides  []Override
+	Definition        Definition[T]
+	Imports           bool
+	Overlay           string
+	Filesystem        *FilesystemContext
+	Overrides         []Override
+	SourceVersionMode SourceVersionMode
 }
 
 // FilesystemContext supplies roots for imports and overlays. With FS nil,
@@ -226,9 +250,10 @@ func (v *Validation) engineContext() *engine.Validation {
 
 func toEngineOptions[T any](options Options[T]) engine.Options[T] {
 	result := engine.Options[T]{
-		Definition: toEngineDefinition(options.Definition),
-		Imports:    options.Imports,
-		Overlay:    options.Overlay,
+		Definition:        toEngineDefinition(options.Definition),
+		Imports:           options.Imports,
+		Overlay:           options.Overlay,
+		SourceVersionMode: engine.SourceVersionModeFromFacade(uint8(options.SourceVersionMode)),
 	}
 	if options.Filesystem != nil {
 		result.Filesystem = toEngineFilesystemContext(options.Filesystem)