diff --git a/convert.go b/convert.go index 9dbf4e5..8fd5017 100644 --- a/convert.go +++ b/convert.go @@ -283,7 +283,7 @@ func fromBackendResource(v *configuration.BackendResource) *BackendInspection { } func fromPromptResource(v *configuration.PromptResource) *PromptInspection { - out := &PromptInspection{PromptID: v.ID, PromptHash: v.Hash, DefaultProfileID: copyStringPtr(v.DefaultProfile), Description: copyStringPtr(v.Description), SessionID: copyStringPtr(v.SessionID), OutputContract: PromptOutputInspection{Format: OutputFormat(v.Output.Format), ValidationMode: ValidationMode(v.Output.ValidationMode), SchemaPath: copyStringPtr(v.Output.SchemaPath), RepairAttempts: copyIntPtr(v.Output.RepairAttempts)}} + out := &PromptInspection{PromptID: v.ID, PromptHash: v.Hash, DefaultProfileID: copyStringPtr(v.DefaultProfile), Description: copyStringPtr(v.Description), SessionID: copyStringPtr(v.SessionID), OutputContract: PromptOutputInspection{Format: OutputFormat(v.Output.Format), ValidationMode: ValidationMode(v.Output.ValidationMode), Schema: jsonvalue.CloneTrusted(v.Output.Schema), SchemaFile: copyStringPtr(v.Output.SchemaFile), SchemaPath: copyStringPtr(v.Output.SchemaPath), RepairAttempts: copyIntPtr(v.Output.RepairAttempts)}} if v.Inputs != nil { inputs := make([]PromptInputInspection, len(*v.Inputs)) for i, input := range *v.Inputs { diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index c7b8f94..d63f5b6 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -202,6 +202,8 @@ configuration. No option-specific precedence or implicit root remains. ## Stage 3 — Capture Prompt-Owned Schema Selections And References +Status: complete. + Work in `internal/configuration/prompts.go`, resource projections, normalization, and prompt-definition snapshots/hashing. diff --git a/internal/configuration/interpretation_test.go b/internal/configuration/interpretation_test.go index 4a29c97..32c4961 100644 --- a/internal/configuration/interpretation_test.go +++ b/internal/configuration/interpretation_test.go @@ -4,6 +4,7 @@ import ( "context" "strings" "testing" + "testing/fstest" "go.maximumdirect.net/configkit" ) @@ -64,7 +65,10 @@ func TestPromptResolutionNormalizesOutputAndRejectsDuplicateNames(t *testing.T) "messages": []any{map[string]any{"role": "user", "content": "hello"}}, "output": map[string]any{"format": "json", "validation_mode": "json_schema", "schema_path": " schema.json "}, } - state, err := load(mapping("prompt metadata", map[string]any{"prompts": []any{definition}}), nil) + filesystem := configkit.NewFilesystem("schemas", fstest.MapFS{}) + input := mapping("prompt metadata", map[string]any{"schema_root": ".", "prompts": []any{definition}}) + input.Filesystem = &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."} + state, err := load(input, nil) if err != nil { t.Fatal(err) } diff --git a/internal/configuration/prompts.go b/internal/configuration/prompts.go index 0e04db1..aede9c6 100644 --- a/internal/configuration/prompts.go +++ b/internal/configuration/prompts.go @@ -54,20 +54,20 @@ func (state *loaded) materializePrompts() error { roots[name] = root } for _, resources := range resourceSets(&state.result.Config) { + root := applicationRoot + if selected := roots[resources.namespace]; resources.isCollection && selected != nil { + root = selected + } for index, raw := range resources.prompts { promptBase := resources.bases.prompts.Index(index) if strings.TrimSpace(raw.ID) == "" { return fmt.Errorf("%s: prompt ID must not be blank", promptBase) } fullID := indexedResourceID(resources.namespace, raw.ID) - entry, err := state.materializePrompt(fullID, raw, promptBase, lookupOrigin) + entry, err := state.materializePrompt(fullID, raw, promptBase, root, lookupOrigin) if err != nil { return err } - entry.definition.SchemaRoot = applicationRoot - if root := roots[resources.namespace]; resources.isCollection && root != nil { - entry.definition.SchemaRoot = root - } state.prompts[fullID] = entry } } @@ -78,30 +78,15 @@ func (state *loaded) captureSchemaRoot(root *string, fieldPath configkit.Path, l if root == nil { return nil, nil } - if strings.TrimSpace(*root) == "" { - return nil, fmt.Errorf("%s: schema_root must not be blank", fieldPath) - } - field, found := lookupOrigin(fieldPath) - if !found || len(field.Origin.Locations) != 1 { - return nil, fmt.Errorf("%s: schema_root needs one contributing source with a filesystem context", fieldPath) - } - sourceID := field.Origin.Locations[0].SourceID - context, found := state.result.SourceContext(sourceID) - if !found || context.FS == nil { - return nil, fmt.Errorf("%s: schema_root source %s has no filesystem context", fieldPath, sourceID) - } - resolved, _, err := filecatalog.ResolveFSPath(".", context.BaseDir, *root) - if err != nil { - return nil, fmt.Errorf("%s: invalid schema_root: %w", fieldPath, err) - } - return &domain.ResourceBinding{FS: context.FS, Path: resolved}, nil + bound, _, err := state.bindResource(fieldPath, *root, "schema_root", lookupOrigin) + return bound, err } -func (state *loaded) materializePrompt(id string, raw promptConfig, base configkit.Path, lookupOrigin func(configkit.Path) (configkit.FieldInfo, bool)) (*promptEntry, error) { +func (state *loaded) materializePrompt(id string, raw promptConfig, base configkit.Path, root *domain.ResourceBinding, lookupOrigin func(configkit.Path) (configkit.FieldInfo, bool)) (*promptEntry, error) { if len(raw.Messages) == 0 { return nil, fmt.Errorf("%s: at least one message is required", base.Key("messages")) } - definition := domain.PromptDefinition{ID: id} + definition := domain.PromptDefinition{ID: id, SchemaRoot: root} if raw.DefaultProfile != nil { if strings.TrimSpace(*raw.DefaultProfile) == "" { return nil, fmt.Errorf("%s: default profile must not be blank", base.Key("default_profile")) @@ -130,6 +115,22 @@ func (state *loaded) materializePrompt(id string, raw promptConfig, base configk definition.Templates = messages entry := &promptEntry{resource: raw, requirementInputs: inputMetadata, messages: compiledMessages} definition.Validation = contract + if contract.ValidationMode == domain.ValidationJSONSchema { + fieldPath := base.Key("output") + if contract.SchemaFile != nil { + definition.SchemaFile, _, err = state.bindResource(fieldPath.Key("schema_file"), *contract.SchemaFile, "schema_file", lookupOrigin) + if err != nil { + return nil, err + } + } else if contract.SchemaPath != "" { + if root == nil { + return nil, fmt.Errorf("%s: schema_path requires an applicable schema_root", fieldPath.Key("schema_path")) + } + if _, _, err := filecatalog.ResolveFSPath(root.Path, root.Path, contract.SchemaPath); err != nil { + return nil, fmt.Errorf("%s: invalid schema_path: %w", fieldPath.Key("schema_path"), err) + } + } + } if raw.SessionID != nil { var err error entry.session, err = prompt.CompileTemplate("session_id", definition.SessionID) @@ -248,8 +249,13 @@ func capturePromptOutput(output *promptOutputConfig, base configkit.Path) (domai Format: domain.OutputFormat(*output.Format), ValidationMode: domain.ValidationMode(*output.ValidationMode), RepairAttempts: output.RepairAttempts, + Schema: jsonvalue.CloneTrusted(output.Schema), + SchemaFile: stringPointerValue(output.SchemaFile), } if output.SchemaPath != nil { + if contract.ValidationMode == domain.ValidationJSONSchema && strings.TrimSpace(*output.SchemaPath) == "" { + return domain.OutputContract{}, fmt.Errorf("%s: schema_path must not be blank", base.Key("output").Key("schema_path")) + } contract.SchemaPath = *output.SchemaPath } if err := domain.ValidateOutputContract(contract); err != nil { @@ -270,24 +276,32 @@ func stringPointerValue(value *string) *string { return stringPointer(*value) } -func (state *loaded) readContent(fieldPath configkit.Path, name string, lookupOrigin func(configkit.Path) (configkit.FieldInfo, bool)) (string, error) { +func (state *loaded) bindResource(fieldPath configkit.Path, name, label string, lookupOrigin func(configkit.Path) (configkit.FieldInfo, bool)) (*domain.ResourceBinding, string, error) { if strings.TrimSpace(name) == "" { - return "", fmt.Errorf("%s: content_file path must not be blank", fieldPath) + return nil, "", fmt.Errorf("%s: %s path must not be blank", fieldPath, label) } field, found := lookupOrigin(fieldPath) if !found || len(field.Origin.Locations) != 1 { - return "", fmt.Errorf("%s: content_file needs one contributing source with a filesystem context", fieldPath) + return nil, "", fmt.Errorf("%s: %s needs one contributing source with a filesystem context", fieldPath, label) } sourceID := field.Origin.Locations[0].SourceID context, found := state.result.SourceContext(sourceID) if !found || context.FS == nil { - return "", fmt.Errorf("%s: content_file source %s has no filesystem context", fieldPath, sourceID) + return nil, "", fmt.Errorf("%s: %s source %s has no filesystem context", fieldPath, label, sourceID) } resolved, _, err := filecatalog.ResolveFSPath(".", context.BaseDir, name) if err != nil { - return "", fmt.Errorf("%s: content_file path is outside its source root or invalid: %w", fieldPath, err) + return nil, "", fmt.Errorf("%s: %s path is outside its source root or invalid: %w", fieldPath, label, err) } - file, err := context.FS.Open(resolved) + return &domain.ResourceBinding{FS: context.FS, Path: resolved}, sourceID, nil +} + +func (state *loaded) readContent(fieldPath configkit.Path, name string, lookupOrigin func(configkit.Path) (configkit.FieldInfo, bool)) (string, error) { + binding, sourceID, err := state.bindResource(fieldPath, name, "content_file", lookupOrigin) + if err != nil { + return "", err + } + file, err := binding.FS.Open(binding.Path) if err != nil { return "", fmt.Errorf("%s: open content_file from source %s: %w", fieldPath, sourceID, err) } diff --git a/internal/configuration/resources.go b/internal/configuration/resources.go index 205d76a..728577e 100644 --- a/internal/configuration/resources.go +++ b/internal/configuration/resources.go @@ -95,7 +95,7 @@ func (state *loaded) InspectPrompt(ctx context.Context, id string) (*PromptResou result.Messages[i].CacheControl = &PromptCacheControlResource{Type: message.CacheControl.Type, TTL: raw.Messages[i].CacheControl.TTL} } } - result.Output = PromptOutputResource{Format: entry.definition.Validation.Format, ValidationMode: entry.definition.Validation.ValidationMode, SchemaPath: raw.Output.SchemaPath} + result.Output = PromptOutputResource{Format: entry.definition.Validation.Format, ValidationMode: entry.definition.Validation.ValidationMode, Schema: entry.definition.Validation.Schema, SchemaFile: raw.Output.SchemaFile, SchemaPath: raw.Output.SchemaPath} if state.promptRepair[id] { value := raw.Output.RepairAttempts result.Output.RepairAttempts = &value diff --git a/internal/configuration/schema_capture_test.go b/internal/configuration/schema_capture_test.go new file mode 100644 index 0000000..721216f --- /dev/null +++ b/internal/configuration/schema_capture_test.go @@ -0,0 +1,132 @@ +package configuration + +import ( + "context" + "io/fs" + "strings" + "testing" + "testing/fstest" + + "go.maximumdirect.net/configkit" +) + +func schemaPrompt(id string, output map[string]any) map[string]any { + return map[string]any{"id": id, "messages": []any{map[string]any{"role": "user", "content": "hello"}}, "output": output} +} + +func TestSchemaFileCaptureUsesEffectiveSource(t *testing.T) { + first := configkit.NewFilesystem("first", fstest.MapFS{"a/placeholder": {Data: []byte("x")}, "a/schema.json": {Data: []byte("first")}}) + second := configkit.NewFilesystem("second", fstest.MapFS{"b/placeholder": {Data: []byte("x")}, "b/schema.json": {Data: []byte("second")}}) + base := configkit.Input{Source: configkit.Mapping("base", map[string]any{"prompts": []any{ + schemaPrompt("base", map[string]any{"format": "json", "validation_mode": "json_schema", "schema_file": "schema.json"}), + map[string]any{"id": "inherited", "extends": map[string]any{"id": "base"}}, + map[string]any{"id": "override", "extends": map[string]any{"id": "base"}}, + }}), Filesystem: &configkit.FilesystemContext{FS: &first, Root: ".", BaseDir: "a"}} + overlay := configkit.Input{Source: configkit.Mapping("override", map[string]any{"prompts": []any{ + map[string]any{"id": "override", "extends": map[string]any{"id": "base"}, "output": map[string]any{"schema_file": "schema.json"}}, + schemaPrompt("missing", map[string]any{"format": "json", "validation_mode": "json_schema", "schema_file": "missing.json"}), + }}), Filesystem: &configkit.FilesystemContext{FS: &second, Root: ".", BaseDir: "b"}} + state, err := load(overlay, []configkit.Underlay{{Inputs: []configkit.Input{base}}}) + if err != nil { + t.Fatal(err) + } + for id, want := range map[string]string{"base": "first", "inherited": "first", "override": "second"} { + definition, _, err := state.prompt(id) + if err != nil { + t.Fatal(err) + } + data, err := fs.ReadFile(definition.SchemaFile.FS, definition.SchemaFile.Path) + if err != nil || string(data) != want { + t.Fatalf("%s = %q, %v", id, data, err) + } + } + missing, err := state.InspectPrompt(context.Background(), "missing") + if err != nil || missing.Output.SchemaFile == nil || *missing.Output.SchemaFile != "missing.json" { + t.Fatalf("missing inspection = %+v, %v", missing, err) + } +} + +func TestSchemaInlineCompositionAndSelection(t *testing.T) { + base := mapping("base", map[string]any{"prompts": []any{ + schemaPrompt("inline-base", map[string]any{"format": "json", "validation_mode": "json_schema", "schema": map[string]any{"type": "object", "properties": map[string]any{"a": map[string]any{"type": "string"}}}}), + schemaPrompt("switch-base", map[string]any{"format": "json", "validation_mode": "none", "schema_file": "unused.json"}), + }}) + main := mapping("override", map[string]any{"prompts": []any{ + map[string]any{"id": "inline", "extends": map[string]any{"id": "inline-base"}, "output": map[string]any{"schema": map[string]any{"properties": map[string]any{"b": map[string]any{"type": "number"}}}}}, + map[string]any{"id": "switch", "extends": map[string]any{"id": "switch-base"}, "output": map[string]any{"validation_mode": "json_schema", "schema_file": nil, "schema": false}}, + }}) + state, err := load(main, []configkit.Underlay{{Inputs: []configkit.Input{base}}}) + if err != nil { + t.Fatal(err) + } + definition, inspection, err := state.prompt("inline") + if err != nil { + t.Fatal(err) + } + properties := definition.Validation.Schema.(map[string]any)["properties"].(map[string]any) + if len(properties) != 2 || properties["a"] == nil || properties["b"] == nil { + t.Fatalf("merged properties: %#v", properties) + } + properties["a"] = false + again, _, err := state.prompt("inline") + if err != nil || again.Validation.Schema.(map[string]any)["properties"].(map[string]any)["a"] == false { + t.Fatalf("schema not detached: %+v, %v", again, err) + } + if inspection.PromptHash == "" { + t.Fatal("missing definition hash") + } + switched, _, err := state.prompt("switch") + if err != nil || switched.Validation.Schema != false || switched.Validation.SchemaFile != nil { + t.Fatalf("switch = %+v, %v", switched, err) + } +} + +func TestSchemaSelectionMetadataFailures(t *testing.T) { + for _, tc := range []struct { + name string + output map[string]any + want string + }{ + {"missing root", map[string]any{"schema_path": "x.json"}, "schema_root"}, + {"missing context", map[string]any{"schema_file": "x.json"}, "filesystem context"}, + {"blank path", map[string]any{"schema": false, "schema_path": " "}, "schema_path"}, + {"conflicting", map[string]any{"schema": false, "schema_file": "x.json"}, "exactly one"}, + } { + t.Run(tc.name, func(t *testing.T) { + tc.output["format"], tc.output["validation_mode"] = "json", "json_schema" + _, err := load(mapping("prompt", map[string]any{"prompts": []any{schemaPrompt("p", tc.output)}}), nil) + if err == nil || !strings.Contains(err.Error(), tc.want) { + t.Fatalf("error = %v, want %s", err, tc.want) + } + }) + } + _, err := load(mapping("inactive", map[string]any{"prompts": []any{schemaPrompt("p", map[string]any{"format": "text", "validation_mode": "none", "schema_file": "../unused", "schema_path": " "})}}), nil) + if err != nil { + t.Fatalf("inactive references: %v", err) + } +} + +func TestSchemaSelectionsContributeToDefinitionHash(t *testing.T) { + filesystem := configkit.NewFilesystem("fixtures", fstest.MapFS{}) + hash := func(output map[string]any) string { + t.Helper() + output["format"], output["validation_mode"] = "json", "json_schema" + input := mapping("prompt", map[string]any{"prompts": []any{schemaPrompt("p", output)}}) + input.Filesystem = &configkit.FilesystemContext{FS: &filesystem, Root: ".", BaseDir: "."} + state, err := load(input, nil) + if err != nil { + t.Fatal(err) + } + _, inspection, err := state.prompt("p") + if err != nil { + t.Fatal(err) + } + return inspection.PromptHash + } + if hash(map[string]any{"schema": false}) == hash(map[string]any{"schema": true}) { + t.Fatal("distinct inline values produced the same definition hash") + } + if hash(map[string]any{"schema_file": "one.json"}) == hash(map[string]any{"schema_file": "two.json"}) { + t.Fatal("distinct references produced the same definition hash") + } +}