Escape schema resources and reuse compiled plans

internal/usecase/prepared_execution.go

@@ -42,25 +42,12 @@ func (r *Runner) PrepareExecution(ctx context.Context, req domain.RunRequest) (*
 		return nil, err
 	}
 
-	validationPlan, err := r.prepareValidation(ctx, state.effectiveContract)
+	operation, err := r.completePreparation(ctx, req, state)
 	if err != nil {
 		return nil, err
 	}
 
-	structuredOutput, err := r.structuredOutputFromValidationPlan(
-		state.definition,
-		state.effectiveContract,
-		validationPlan,
-	)
-	if err != nil {
-		return nil, err
-	}
-	prepared, err := r.completePreparationWithStructuredOutput(ctx, req, state, structuredOutput)
-	if err != nil {
-		return nil, err
-	}
-
-	executionSnapshot, err := clonePreparedRun(prepared)
+	executionSnapshot, err := clonePreparedRun(operation.run)
 	if err != nil {
 		return nil, fmt.Errorf("%w: failed to copy prepared execution: %v", ErrInvalidRequest, err)
 	}
@@ -76,52 +63,12 @@ func (r *Runner) PrepareExecution(ctx context.Context, req domain.RunRequest) (*
 		details: details,
 		payload: &preparedExecutionPayload{
 			prepared:   executionSnapshot,
-			validation: validationPlan,
+			validation: operation.validation,
 			directKey:  state.effectiveModel.APIKey,
 		},
 	}, nil
 }
 
-func (r *Runner) prepareValidation(
-	ctx context.Context,
-	contract domain.OutputContract,
-) (validate.PreparedValidation, error) {
-	if r.validator == nil {
-		return noOpPreparedValidation{contract: contract}, nil
-	}
-	preparer, ok := r.validator.(validate.ValidationPreparer)
-	if !ok {
-		return nil, fmt.Errorf("%w: validator does not support prepared validation", ErrValidation)
-	}
-	plan, err := preparer.PrepareValidation(ctx, contract)
-	if err != nil {
-		return nil, fmt.Errorf("%w: %w", ErrValidation, err)
-	}
-	if plan == nil {
-		return nil, fmt.Errorf("%w: validator returned nil prepared validation", ErrValidation)
-	}
-	return plan, nil
-}
-
-func (r *Runner) structuredOutputFromValidationPlan(
-	def *domain.PromptDefinition,
-	contract domain.OutputContract,
-	plan validate.PreparedValidation,
-) (*domain.StructuredOutputSpec, error) {
-	if contract.ValidationMode != domain.ValidationJSONSchema {
-		return nil, nil
-	}
-
-	schemaDocument := plan.SchemaDocument()
-	if schemaDocument == nil {
-		if r.validator == nil {
-			return nil, nil
-		}
-		return nil, fmt.Errorf("%w: prepared json_schema validation has no schema document", ErrValidation)
-	}
-	return structuredOutputSpec(def, schemaDocument), nil
-}
-
 // Details returns a fresh credential-redacted copy of the prepared run.
 func (p *PreparedExecution) Details() *domain.PreparedRun {
 	if p == nil {

internal/usecase/prepared_execution_test.go

@@ -52,6 +52,12 @@ type recordingValidationPreparer struct {
 	directValidateCalls int
 }
 
+type validationOnly struct{}
+
+func (validationOnly) Validate(context.Context, *domain.Artifact, domain.OutputContract) (domain.ValidationResult, error) {
+	return domain.ValidationResult{}, nil
+}
+
 func (v *recordingValidationPreparer) Validate(
 	context.Context,
 	*domain.Artifact,
@@ -532,7 +538,7 @@ func TestRunnerPrepareExecutionRequiresValidationPreparer(t *testing.T) {
 		reader,
 		defaultRenderer(),
 		&fakeLLM{forbid: true},
-		&fakeValidator{},
+		validationOnly{},
 		nil,
 	)
 

internal/usecase/runner.go

@@ -71,6 +71,11 @@ type preparationState struct {
 	start                time.Time
 }
 
+type preparedOperation struct {
+	run        *domain.PreparedRun
+	validation validate.PreparedValidation
+}
+
 func NewRunner(
 	promptDefs promptdef.Repository,
 	profiles profile.Repository,
@@ -137,18 +142,20 @@ func (r *Runner) Run(ctx context.Context, req domain.RunRequest) (*domain.RunRes
 	}
 	defer release()
 
-	prepared, err := r.completePreparation(ctx, req, state)
+	operation, err := r.completePreparation(ctx, req, state)
 	if err != nil {
 		return nil, err
 	}
 	directAPIKey := state.effectiveModel.APIKey
 
-	return r.executePreparedRun(ctx, prepared, directAPIKey, runID, start, func(
+	return r.executePreparedRun(ctx, operation.run, directAPIKey, runID, start, func(
 		ctx context.Context,
 		artifact *domain.Artifact,
 		attemptsUsed int,
 	) (domain.ValidationResult, error) {
-		return r.validateOutput(ctx, artifact, prepared.OutputContract, attemptsUsed)
+		result, err := operation.validation.Validate(ctx, artifact)
+		result.RepairAttempts = attemptsUsed
+		return result, err
 	})
 }
 
@@ -250,7 +257,11 @@ func (r *Runner) Prepare(ctx context.Context, req domain.RunRequest) (*domain.Pr
 	if err != nil {
 		return nil, err
 	}
-	return r.completePreparation(ctx, req, state)
+	operation, err := r.completePreparation(ctx, req, state)
+	if err != nil {
+		return nil, err
+	}
+	return operation.run, nil
 }
 
 func (r *Runner) resolvePreparation(
@@ -315,16 +326,64 @@ func (r *Runner) completePreparation(
 	ctx context.Context,
 	req domain.RunRequest,
 	state *preparationState,
-) (*domain.PreparedRun, error) {
-	structuredOutput, err := r.resolveStructuredOutput(
-		ctx,
+) (*preparedOperation, error) {
+	validationPlan, err := r.prepareValidation(ctx, state.effectiveContract)
+	if err != nil {
+		return nil, err
+	}
+	structuredOutput, err := r.structuredOutputFromValidationPlan(
 		state.definition,
 		state.effectiveContract,
+		validationPlan,
 	)
 	if err != nil {
 		return nil, err
 	}
-	return r.completePreparationWithStructuredOutput(ctx, req, state, structuredOutput)
+	prepared, err := r.completePreparationWithStructuredOutput(ctx, req, state, structuredOutput)
+	if err != nil {
+		return nil, err
+	}
+	return &preparedOperation{run: prepared, validation: validationPlan}, nil
+}
+
+func (r *Runner) prepareValidation(
+	ctx context.Context,
+	contract domain.OutputContract,
+) (validate.PreparedValidation, error) {
+	if r.validator == nil {
+		return noOpPreparedValidation{contract: contract}, nil
+	}
+	preparer, ok := r.validator.(validate.ValidationPreparer)
+	if !ok {
+		return nil, fmt.Errorf("%w: validator does not support prepared validation", ErrValidation)
+	}
+	plan, err := preparer.PrepareValidation(ctx, contract)
+	if err != nil {
+		return nil, fmt.Errorf("%w: %w", ErrValidation, err)
+	}
+	if plan == nil {
+		return nil, fmt.Errorf("%w: validator returned nil prepared validation", ErrValidation)
+	}
+	return plan, nil
+}
+
+func (r *Runner) structuredOutputFromValidationPlan(
+	def *domain.PromptDefinition,
+	contract domain.OutputContract,
+	plan validate.PreparedValidation,
+) (*domain.StructuredOutputSpec, error) {
+	if contract.ValidationMode != domain.ValidationJSONSchema {
+		return nil, nil
+	}
+
+	schemaDocument := plan.SchemaDocument()
+	if schemaDocument == nil {
+		if r.validator == nil {
+			return nil, nil
+		}
+		return nil, fmt.Errorf("%w: prepared json_schema validation has no schema document", ErrValidation)
+	}
+	return structuredOutputSpec(def, schemaDocument), nil
 }
 
 func (r *Runner) completePreparationWithStructuredOutput(
@@ -398,24 +457,6 @@ func (r *Runner) admitRun(ctx context.Context, backendID string) (func(), error)
 	return release, nil
 }
 
-func (r *Runner) resolveStructuredOutput(ctx context.Context, def *domain.PromptDefinition, contract domain.OutputContract) (*domain.StructuredOutputSpec, error) {
-	if contract.ValidationMode != domain.ValidationJSONSchema {
-		return nil, nil
-	}
-
-	loader, ok := r.validator.(validate.SchemaDocumentLoader)
-	if !ok || loader == nil {
-		return nil, fmt.Errorf("%w: json_schema output requires schema document loader", ErrValidation)
-	}
-
-	schemaDoc, err := loader.LoadSchemaDocument(ctx, contract.SchemaPath)
-	if err != nil {
-		return nil, fmt.Errorf("%w: failed to load json schema for structured output: %v", ErrValidation, err)
-	}
-
-	return structuredOutputSpec(def, schemaDoc), nil
-}
-
 func structuredOutputSpec(def *domain.PromptDefinition, schemaDocument any) *domain.StructuredOutputSpec {
 	return &domain.StructuredOutputSpec{
 		Type: domain.StructuredOutputJSONSchema,
@@ -453,25 +494,6 @@ func deriveStructuredSchemaName(promptID string, promptVersion string) string {
 	return name
 }
 
-func (r *Runner) validateOutput(ctx context.Context, artifact *domain.Artifact, contract domain.OutputContract, attemptsUsed int) (domain.ValidationResult, error) {
-	if r.validator == nil || contract.ValidationMode == domain.ValidationNone {
-		return domain.ValidationResult{
-			Status:         domain.ValidationSkipped,
-			Mode:           contract.ValidationMode,
-			SchemaPath:     contract.SchemaPath,
-			RepairAttempts: attemptsUsed,
-			IsValid:        true,
-		}, nil
-	}
-
-	res, err := r.validator.Validate(ctx, artifact, contract)
-	if err != nil {
-		return domain.ValidationResult{}, err
-	}
-	res.RepairAttempts = attemptsUsed
-	return res, nil
-}
-
 func (r *Runner) shouldAttemptRepair(contract domain.OutputContract, validationResult domain.ValidationResult) bool {
 	if r.repairer == nil {
 		return false

internal/usecase/runner_test.go

@@ -191,16 +191,34 @@ func (f *fakeValidator) Validate(ctx context.Context, artifact *domain.Artifact,
 	return f.result, nil
 }
 
-func (f *fakeValidator) LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error) {
-	f.schemaLoads++
-	f.schemaLoadPath = schemaPath
-	if f.schemaErr != nil {
-		return nil, f.schemaErr
+func (f *fakeValidator) PrepareValidation(_ context.Context, contract domain.OutputContract) (validate.PreparedValidation, error) {
+	var schemaDocument any
+	if contract.ValidationMode == domain.ValidationJSONSchema {
+		f.schemaLoads++
+		f.schemaLoadPath = contract.SchemaPath
+		if f.schemaErr != nil {
+			return nil, f.schemaErr
+		}
+		schemaDocument = f.schemaDoc
+		if schemaDocument == nil {
+			schemaDocument = map[string]any{"type": "object"}
+		}
 	}
-	if f.schemaDoc != nil {
-		return f.schemaDoc, nil
-	}
-	return map[string]any{"type": "object"}, nil
+	return &fakePreparedValidator{validator: f, contract: contract, schemaDocument: schemaDocument}, nil
+}
+
+type fakePreparedValidator struct {
+	validator      *fakeValidator
+	contract       domain.OutputContract
+	schemaDocument any
+}
+
+func (p *fakePreparedValidator) Validate(ctx context.Context, artifact *domain.Artifact) (domain.ValidationResult, error) {
+	return p.validator.Validate(ctx, artifact, p.contract)
+}
+
+func (p *fakePreparedValidator) SchemaDocument() any {
+	return p.schemaDocument
 }
 
 type fakeRepairer struct {
@@ -2278,6 +2296,9 @@ func TestRunnerRunJSONSchemaRepairCarriesStructuredOutputSpec(t *testing.T) {
 	if repairer.reqs[0].StructuredOutput.JSONSchema.Name != "p_1" {
 		t.Fatalf("expected derived schema name p_1, got %q", repairer.reqs[0].StructuredOutput.JSONSchema.Name)
 	}
+	if validator.schemaLoads != 1 || validator.validateCalls != 2 {
+		t.Fatalf("schema preparation/validation calls = (%d, %d), want (1, 2)", validator.schemaLoads, validator.validateCalls)
+	}
 }
 
 func TestExecutionProfileToTargetPopulatesAllFieldsAndCopiesExtraParams(t *testing.T) {

internal/validate/standard_validator.go

@@ -12,6 +12,7 @@ import (
 	"os"
 	"path"
 	"path/filepath"
+	"runtime"
 	"strings"
 
 	"gitea.maximumdirect.net/eric/promptkit/internal/domain"
@@ -94,10 +95,11 @@ func (v *StandardValidator) PrepareValidation(ctx context.Context, contract doma
 		return nil, err
 	}
 	compiler := newSchemaCompiler(standardSchemaLoader{root: schemaRoot})
-	if err := compiler.AddResource(resolvedSchemaPath, schemaDocument); err != nil {
+	resourceURL := fileSchemaResourceURL(resolvedSchemaPath)
+	if err := compiler.AddResource(resourceURL.String(), schemaDocument); err != nil {
 		return nil, fmt.Errorf("failed to register JSON schema %q: %w", resolvedSchemaPath, err)
 	}
-	schema, err := compiler.Compile(resolvedSchemaPath)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", resolvedSchemaPath, err)
 	}
@@ -126,10 +128,10 @@ func (v *FSValidator) PrepareValidation(ctx context.Context, contract domain.Out
 	}
 	resourceURL := fsSchemaResourceURL(schemaName)
 	compiler := newSchemaCompiler(fsSchemaLoader{fsys: v.fsys, root: filecatalog.CleanFSRoot(v.root)})
-	if err := compiler.AddResource(resourceURL, schemaDocument); err != nil {
+	if err := compiler.AddResource(resourceURL.String(), schemaDocument); err != nil {
 		return nil, fmt.Errorf("failed to register JSON schema %q: %w", schemaName, err)
 	}
-	schema, err := compiler.Compile(resourceURL)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", schemaName, err)
 	}
@@ -225,7 +227,8 @@ func (v *StandardValidator) validateJSONSchema(instance any, schemaPath string)
 		return nil, err
 	}
 	compiler := newSchemaCompiler(standardSchemaLoader{root: schemaRoot})
-	schema, err := compiler.Compile(resolvedSchemaPath)
+	resourceURL := fileSchemaResourceURL(resolvedSchemaPath)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", resolvedSchemaPath, err)
 	}
@@ -247,10 +250,10 @@ func (v *FSValidator) validateJSONSchema(instance any, schemaPath string) ([]str
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", schemaName, err)
 	}
 	compiler := newSchemaCompiler(fsSchemaLoader{fsys: v.fsys, root: filecatalog.CleanFSRoot(v.root)})
-	if err := compiler.AddResource(resourceURL, schemaDoc); err != nil {
+	if err := compiler.AddResource(resourceURL.String(), schemaDoc); err != nil {
 		return nil, fmt.Errorf("failed to register JSON schema %q: %w", schemaName, err)
 	}
-	schema, err := compiler.Compile(resourceURL)
+	schema, err := compiler.Compile(resourceURL.String())
 	if err != nil {
 		return nil, fmt.Errorf("failed to compile JSON schema %q: %w", schemaName, err)
 	}
@@ -279,47 +282,6 @@ func decodeJSONValue(body []byte) (any, error) {
 	return nil, errors.New("multiple JSON values")
 }
 
-func (v *StandardValidator) LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error) {
-	select {
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	default:
-	}
-
-	resolved, err := v.resolveSchemaPath(schemaPath)
-	if err != nil {
-		return nil, err
-	}
-
-	raw, err := os.ReadFile(resolved)
-	if err != nil {
-		return nil, fmt.Errorf("failed to read schema file %q: %w", resolved, err)
-	}
-
-	doc, err := decodeJSONValue(raw)
-	if err != nil {
-		return nil, fmt.Errorf("failed to decode JSON schema %q: %w", resolved, err)
-	}
-	if err := validateSchemaDialect(doc); err != nil {
-		return nil, fmt.Errorf("failed to decode JSON schema %q: %w", resolved, err)
-	}
-	return doc, nil
-}
-
-func (v *FSValidator) LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error) {
-	select {
-	case <-ctx.Done():
-		return nil, ctx.Err()
-	default:
-	}
-
-	_, doc, err := v.loadSchemaDocument(schemaPath)
-	if err != nil {
-		return nil, err
-	}
-	return doc, nil
-}
-
 func (v *StandardValidator) resolveSchemaPath(schemaPath string) (string, error) {
 	if strings.TrimSpace(schemaPath) == "" {
 		return "", errors.New("schema path is required for json_schema validation")
@@ -427,8 +389,19 @@ func cleanSchemaFSPath(schemaPath string) (string, error) {
 	return cleaned, nil
 }
 
-func fsSchemaResourceURL(schemaName string) string {
-	return "promptkit-schema:///" + strings.TrimPrefix(path.Clean(schemaName), "/")
+func fileSchemaResourceURL(schemaName string) *url.URL {
+	filePath := filepath.ToSlash(schemaName)
+	if runtime.GOOS == "windows" && !strings.HasPrefix(filePath, "/") {
+		filePath = "/" + filePath
+	}
+	return &url.URL{Scheme: "file", Path: filePath}
+}
+
+func fsSchemaResourceURL(schemaName string) *url.URL {
+	return &url.URL{
+		Scheme: "promptkit-schema",
+		Path:   "/" + strings.TrimPrefix(path.Clean(schemaName), "/"),
+	}
 }
 
 func newSchemaCompiler(loader jsonschema.URLLoader) *jsonschema.Compiler {
@@ -462,6 +435,10 @@ type standardSchemaLoader struct {
 }
 
 func (l standardSchemaLoader) Load(resourceURL string) (any, error) {
+	parsed, err := url.Parse(resourceURL)
+	if err != nil || parsed.Scheme != "file" || parsed.Host != "" || parsed.RawQuery != "" || parsed.Opaque != "" {
+		return nil, fmt.Errorf("schema reference %q is not a contained file reference", resourceURL)
+	}
 	fileName, err := (jsonschema.FileLoader{}).ToFile(resourceURL)
 	if err != nil {
 		return nil, fmt.Errorf("schema reference %q is not a contained file reference: %w", resourceURL, err)
@@ -521,13 +498,10 @@ func (l fsSchemaLoader) Load(resourceURL string) (any, error) {
 	if err != nil {
 		return nil, fmt.Errorf("invalid schema reference %q: %w", resourceURL, err)
 	}
-	if parsed.Scheme != "promptkit-schema" || parsed.Host != "" {
+	if parsed.Scheme != "promptkit-schema" || parsed.Host != "" || parsed.RawQuery != "" || parsed.Opaque != "" {
 		return nil, fmt.Errorf("schema reference %q is not allowed", resourceURL)
 	}
-	name, err := url.PathUnescape(strings.TrimPrefix(parsed.Path, "/"))
-	if err != nil {
-		return nil, fmt.Errorf("invalid schema reference %q: %w", resourceURL, err)
-	}
+	name := strings.TrimPrefix(parsed.Path, "/")
 	name = path.Clean(name)
 	if l.root == "." {
 		if strings.HasPrefix(name, "../") || name == ".." {

internal/validate/standard_validator_test.go

@@ -3,9 +3,11 @@ package validate
 import (
 	"context"
 	"encoding/json"
+	"net/url"
 	"os"
 	"path/filepath"
 	"reflect"
+	"runtime"
 	"strconv"
 	"strings"
 	"testing"
@@ -330,55 +332,6 @@ func TestStandardValidatorJSONSchemaCompilationError(t *testing.T) {
 	}
 }
 
-func TestStandardValidatorLoadSchemaDocumentSuccess(t *testing.T) {
-	tmp := t.TempDir()
-	if err := os.WriteFile(filepath.Join(tmp, "schema.json"), []byte(`{
-  "type": "object",
-  "properties": {
-    "name": {"type": "string"}
-  }
-}`), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	v := NewStandardValidator(tmp)
-	loader, ok := v.(SchemaDocumentLoader)
-	if !ok {
-		t.Fatal("standard validator must implement SchemaDocumentLoader")
-	}
-
-	doc, err := loader.LoadSchemaDocument(context.Background(), "schema.json")
-	if err != nil {
-		t.Fatalf("expected no error, got %v", err)
-	}
-
-	obj, ok := doc.(map[string]any)
-	if !ok {
-		t.Fatalf("expected object document, got %#v", doc)
-	}
-	if obj["type"] != "object" {
-		t.Fatalf("expected schema type=object, got %#v", obj["type"])
-	}
-}
-
-func TestStandardValidatorLoadSchemaDocumentInvalidJSON(t *testing.T) {
-	tmp := t.TempDir()
-	if err := os.WriteFile(filepath.Join(tmp, "schema.json"), []byte(`{`), 0644); err != nil {
-		t.Fatal(err)
-	}
-
-	v := NewStandardValidator(tmp)
-	loader, ok := v.(SchemaDocumentLoader)
-	if !ok {
-		t.Fatal("standard validator must implement SchemaDocumentLoader")
-	}
-
-	_, err := loader.LoadSchemaDocument(context.Background(), "schema.json")
-	if err == nil {
-		t.Fatal("expected decode error")
-	}
-}
-
 func TestFSValidatorJSONSchemaSuccess(t *testing.T) {
 	v := NewFSValidator(fstest.MapFS{
 		"schemas/events.schema.json": &fstest.MapFile{Data: []byte(`{
@@ -461,17 +414,70 @@ func TestFSValidatorPreparedSchemaSurvivesSourceMutation(t *testing.T) {
 	}
 }
 
-func TestFSValidatorJSONSchemaRegistrationError(t *testing.T) {
-	v := NewFSValidator(fstest.MapFS{
-		"schemas/%zz.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
-	}, "schemas")
+func TestFSValidatorEscapesSchemaResourcePath(t *testing.T) {
+	for _, schemaName := range []string{"%zz.json", "space name.json", "hash#.json", "query?.json", "rún.json"} {
+		t.Run(schemaName, func(t *testing.T) {
+			v := NewFSValidator(fstest.MapFS{
+				"schemas/" + schemaName: &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
+			}, "schemas")
 
-	res, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{}`)}, domain.OutputContract{
+			res, err := v.Validate(context.Background(), &domain.Artifact{Body: []byte(`{}`)}, domain.OutputContract{
+				ValidationMode: domain.ValidationJSONSchema,
+				SchemaPath:     schemaName,
+			})
+			if err != nil || !res.IsValid {
+				t.Fatalf("validate schema %q: result=%#v error=%v", schemaName, res, err)
+			}
+		})
+	}
+}
+
+func TestSchemaReferencesPreserveEscapedFilenames(t *testing.T) {
+	for _, name := range []string{"%2F.json", "space name.json", "hash#.json", "query?.json", "rún.json"} {
+		t.Run(name, func(t *testing.T) {
+			rootName := "root-" + name
+			childName := "child-" + name
+			childPath := "nested/" + childName
+			reference := (&url.URL{Path: childPath}).EscapedPath()
+			rootSchema := []byte(`{"$ref":` + strconv.Quote(reference) + `}`)
+			childSchema := []byte(`{"type":"integer","minimum":2}`)
+
+			t.Run("fs.FS", func(t *testing.T) {
+				validator := NewFSValidator(fstest.MapFS{
+					"schemas/" + rootName:  &fstest.MapFile{Data: rootSchema},
+					"schemas/" + childPath: &fstest.MapFile{Data: childSchema},
+				}, "schemas")
+				assertSchemaValidation(t, validator, rootName)
+			})
+
+			t.Run("operating system files", func(t *testing.T) {
+				if runtime.GOOS == "windows" && strings.ContainsAny(rootName+childName, `<>:"/\|?*`) {
+					t.Skip("filename is not legal on Windows")
+				}
+				root := t.TempDir()
+				if err := os.Mkdir(filepath.Join(root, "nested"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(filepath.Join(root, rootName), rootSchema, 0o644); err != nil {
+					t.Fatal(err)
+				}
+				if err := os.WriteFile(filepath.Join(root, filepath.FromSlash(childPath)), childSchema, 0o644); err != nil {
+					t.Fatal(err)
+				}
+				assertSchemaValidation(t, NewStandardValidator(root), rootName)
+			})
+		})
+	}
+}
+
+func assertSchemaValidation(t *testing.T, validator Validator, schemaPath string) {
+	t.Helper()
+	result, err := validator.Validate(context.Background(), &domain.Artifact{Body: []byte(`2`)}, domain.OutputContract{
 		ValidationMode: domain.ValidationJSONSchema,
-		SchemaPath:     "%zz.json",
+		SchemaPath:     schemaPath,
 	})
-	if err == nil || !strings.Contains(err.Error(), "failed to register JSON schema") {
-		t.Fatalf("expected schema registration error, got result=%#v error=%v", res, err)
+	if err != nil || !result.IsValid {
+		t.Fatalf("validate schema %q: result=%#v error=%v", schemaPath, result, err)
 	}
 }
 
@@ -561,25 +567,6 @@ func TestFSValidatorSingleSchemaFileUsesBaseName(t *testing.T) {
 	}
 }
 
-func TestFSValidatorLoadSchemaDocument(t *testing.T) {
-	v := NewFSValidator(fstest.MapFS{
-		"schemas/schema.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)},
-	}, "schemas")
-	loader, ok := v.(SchemaDocumentLoader)
-	if !ok {
-		t.Fatal("fs validator must implement SchemaDocumentLoader")
-	}
-
-	doc, err := loader.LoadSchemaDocument(context.Background(), "schema.json")
-	if err != nil {
-		t.Fatalf("expected no error, got %v", err)
-	}
-	obj, ok := doc.(map[string]any)
-	if !ok || obj["type"] != "object" {
-		t.Fatalf("unexpected schema document: %#v", doc)
-	}
-}
-
 func TestStandardValidatorJSONSchemaReferenceBoundaries(t *testing.T) {
 	root := t.TempDir()
 	if err := os.WriteFile(filepath.Join(root, "child.json"), []byte(`{

internal/validate/validator.go

@@ -24,8 +24,3 @@ type PreparedValidation interface {
 type ValidationPreparer interface {
 	PrepareValidation(ctx context.Context, contract domain.OutputContract) (PreparedValidation, error)
 }
-
-// SchemaDocumentLoader loads JSON schema documents using validator path semantics.
-type SchemaDocumentLoader interface {
-	LoadSchemaDocument(ctx context.Context, schemaPath string) (any, error)
-}