From 2348730820358bc5ac261683890f78b4bbd5fb40 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 22 Nov 2026 00:07:05 +0000 Subject: [PATCH] Separate reconciliation preparation and proposal assessment from native execution --- .../deduplication/prompts/correction.md | 6 + .../deduplication/prompts/prompt.yaml | 17 +- docs/roadmap/implementation.md | 17 + .../framework/semanticreconcile/assets.go | 111 ----- .../semanticreconcile/assets_test.go | 146 ++---- internal/framework/semanticreconcile/doc.go | 5 +- .../framework/semanticreconcile/engine.go | 254 ---------- .../semanticreconcile/engine_test.go | 451 ++++++------------ .../framework/semanticreconcile/identity.go | 101 ---- .../semanticreconcile/identity_test.go | 93 ---- .../semanticreconcile/preparation.go | 34 +- .../semanticreconcile/preparation_test.go | 30 +- .../framework/semanticreconcile/proposal.go | 52 +- .../semanticreconcile/proposal_test.go | 36 +- .../framework/semanticreconcile/requests.go | 34 ++ .../framework/semanticreconcile/schema.go | 41 -- .../semanticreconcile/schema_test.go | 37 +- 17 files changed, 327 insertions(+), 1138 deletions(-) create mode 100644 assets/generic/normalize/deduplication/prompts/correction.md delete mode 100644 internal/framework/semanticreconcile/assets.go delete mode 100644 internal/framework/semanticreconcile/engine.go delete mode 100644 internal/framework/semanticreconcile/identity.go delete mode 100644 internal/framework/semanticreconcile/identity_test.go create mode 100644 internal/framework/semanticreconcile/requests.go delete mode 100644 internal/framework/semanticreconcile/schema.go diff --git a/assets/generic/normalize/deduplication/prompts/correction.md b/assets/generic/normalize/deduplication/prompts/correction.md new file mode 100644 index 00000000..53c4f77d --- /dev/null +++ b/assets/generic/normalize/deduplication/prompts/correction.md @@ -0,0 +1,6 @@ +Revise the previous duplicate-entity proposal using these findings: + +{{ input "guidance" }} + +Return one complete replacement proposal under the original output contract. +Do not return a patch or commentary. diff --git a/assets/generic/normalize/deduplication/prompts/prompt.yaml b/assets/generic/normalize/deduplication/prompts/prompt.yaml index 36f5554b..6fd143d5 100644 --- a/assets/generic/normalize/deduplication/prompts/prompt.yaml +++ b/assets/generic/normalize/deduplication/prompts/prompt.yaml @@ -10,9 +10,9 @@ prompts: messages: - role: system content_file: ./system.md - - role: user + - role: system content_file: ./protocol.md - - role: user + - role: system content_file: ./instructions.md cache_control: type: ephemeral @@ -24,3 +24,16 @@ prompts: format: json validation_mode: json_schema schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json + + - id: generic.semantic_reconciliation.repair + inputs: + - name: guidance + required: true + content_type: text/plain + messages: + - role: user + content_file: ./correction.md + output: + format: json + validation_mode: json_schema + schema_path: generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 51811bf5..22b23465 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -582,6 +582,23 @@ test to a native provider fake, including catalog rejection and final correction ## Stage 13: Refactor The Shared Reconciliation Core +**Status:** Complete. Removed the reconciliation execution service and its +private completion/correction transport, retry classifications, asset/schema +registration, metadata, and fingerprints. The core now exposes fixed owned +preparation bytes, native initial/follow-up request builders, proposal decoding, +and the existing independent safety assessment/application functions. Candidate +handles, declared ranges, bounded source windows, group-safety rules, typed +application, and actionable issue prose remain; the follow-up asset owns the +replacement assignment rather than an application retry message builder. +Added the generic native correction pair with the unchanged response schema and +matching unset profile defaults, moving enduring protocol/policy into initial +system context. Retained domain-neutral regressions and added native provider/ +preparation, structural-failure, fixed-material, and successive-proposal tests. +The complete reconciliation and asset tests, vet, race checks, and +`git diff --check` pass. Domain normalizer and central registration consumers of +the removed APIs remain assigned to Stages 14–15 and 24; no whole-tree compilation +claim is made at this intermediate boundary. + **Goal:** separate one-time evidence preparation from proposal interpretation. **Inspect/change:** `internal/framework/semanticreconcile/{engine,preparation, diff --git a/internal/framework/semanticreconcile/assets.go b/internal/framework/semanticreconcile/assets.go deleted file mode 100644 index 06dbd227..00000000 --- a/internal/framework/semanticreconcile/assets.go +++ /dev/null @@ -1,111 +0,0 @@ -package semanticreconcile - -import ( - "errors" - "fmt" - "io/fs" - - "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" - "gitea.maximumdirect.net/eric/notarius/internal/framework/promptfs" -) - -const ( - PromptID = "generic.semantic_reconciliation" - PromptVersion = "v1" - promptRoot = "assets/prompts" -) - -var promptFiles = []promptfs.ModulePromptFile{ - {Name: "prompt.yaml", Path: "prompts/prompt.yaml"}, - {Name: "system.md", Path: "prompts/system.md"}, - {Name: "protocol.md", Path: "prompts/protocol.md"}, - {Name: "instructions.md", Path: "prompts/instructions.md"}, - {Name: "candidates.md", Path: "prompts/candidates.md"}, - {Name: "transcript-windows.md", Path: "prompts/transcript-windows.md"}, -} - -// RegisterAssets registers the generic reconciliation prompt and response -// schema as one production-owned asset set. -func RegisterAssets(registry *llm.AssetRegistry) error { - if registry == nil { - return fmt.Errorf("semantic reconciliation asset registry must not be nil") - } - if err := ensureAssetsAbsent(registry); err != nil { - return err - } - - assets, err := assetFS() - if err != nil { - return err - } - prompts, err := promptfs.ModulePromptFS(PromptID, assets, append([]promptfs.ModulePromptFile(nil), promptFiles...)) - if err != nil { - return fmt.Errorf("prepare semantic reconciliation prompt assets: %w", err) - } - if err := registry.RegisterPromptFS(prompts, promptRoot); err != nil { - return fmt.Errorf("register semantic reconciliation prompt assets: %w", err) - } - if err := registry.RegisterSchemaFS(assets, "schemas"); err != nil { - return fmt.Errorf("register semantic reconciliation schema assets: %w", err) - } - return nil -} - -// PromptHash returns the deterministic identity of the complete generic prompt. -func PromptHash() (string, error) { - assets, err := assetFS() - if err != nil { - return "", err - } - parts := make([]llm.AssetHashPart, 0, len(promptFiles)) - for _, file := range promptFiles { - parts = append(parts, llm.AssetHashPart{FS: assets, Path: file.Path}) - } - return llm.HashAssets(parts) -} - -// SchemaHash returns the deterministic identity of the response schema. -func SchemaHash() (string, error) { - schema, err := LoadResponseSchema() - if err != nil { - return "", err - } - return schema.SHA256, nil -} - -// SharedPromptFiles returns fresh descriptors for the mandatory protocol and -// variable-input presentation assets that domain prompts may reuse. -func SharedPromptFiles() ([]promptfs.SharedPromptFile, error) { - assets, err := assetFS() - if err != nil { - return nil, err - } - return []promptfs.SharedPromptFile{ - {Name: "protocol.md", FS: assets, Path: "prompts/protocol.md"}, - {Name: "candidates.md", FS: assets, Path: "prompts/candidates.md"}, - {Name: "transcript-windows.md", FS: assets, Path: "prompts/transcript-windows.md"}, - }, nil -} - -func ensureAssetsAbsent(registry *llm.AssetRegistry) error { - prompts, err := registry.PromptFS() - if err != nil { - return fmt.Errorf("inspect registered prompt assets: %w", err) - } - if _, err := fs.Stat(prompts, PromptID+"/prompt.yaml"); err == nil { - return fmt.Errorf("semantic reconciliation prompt assets already registered") - } else if !errors.Is(err, fs.ErrNotExist) { - return fmt.Errorf("inspect semantic reconciliation prompt assets: %w", err) - } - - schemas, err := registry.SchemaFS() - if err != nil { - return fmt.Errorf("inspect registered schema assets: %w", err) - } - if _, err := fs.Stat(schemas, "semantic_reconciliation_llm.v1.json"); err == nil { - return fmt.Errorf("semantic reconciliation schema assets already registered") - } else if !errors.Is(err, fs.ErrNotExist) { - return fmt.Errorf("inspect semantic reconciliation schema assets: %w", err) - } - return nil -} diff --git a/internal/framework/semanticreconcile/assets_test.go b/internal/framework/semanticreconcile/assets_test.go index 86213d6d..97fba0ae 100644 --- a/internal/framework/semanticreconcile/assets_test.go +++ b/internal/framework/semanticreconcile/assets_test.go @@ -2,110 +2,68 @@ package semanticreconcile import ( "context" - "io/fs" "reflect" "strings" "testing" - "time" - "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" - "gitea.maximumdirect.net/eric/notarius/internal/testsupport/promptkitfixture" - "gitea.maximumdirect.net/eric/promptkit" + "go.maximumdirect.net/promptkit" ) -func TestRegisterAssetsPreparesGenericPromptOffline(t *testing.T) { - registry := llm.NewAssetRegistry() - if err := RegisterAssets(registry); err != nil { - t.Fatalf("RegisterAssets() error = %v, want nil", err) - } - engine := promptkitfixture.NewEngine(t, registry, promptkit.Config{Timeout: time.Second}, map[string]promptkit.ProfileConfig{ - "semantic-reconciliation-test": promptkitfixture.Profile("http://127.0.0.1:1/v1", "offline-test-model"), - }) - prepared, err := engine.Prepare(context.Background(), promptkit.RunRequest{ - PromptID: PromptID, PromptVersion: PromptVersion, ProfileID: "semantic-reconciliation-test", - Inputs: map[string]promptkit.ArtifactRef{ - "candidates": promptkit.Inline(`{"candidate_number_range":{"first":1,"last":2},"candidates":[{"candidate_number":1,"label":"Mira"},{"candidate_number":2,"label":"Captain Mira"}]}`), - "transcript": promptkit.Inline(`{"windows":[{"units":[{"unit_id":7,"text":"Mira arrived."}]}]}`), - }, - }) +func TestNativeReconciliationPromptPairPreparesOffline(t *testing.T) { + client := &nativeReconciliationClient{} + engine := newReconciliationEngine(t, client) + preparation := proposalPreparation(t) + initial, err := InitialRequest(preparation, PromptID, "test-profile", "session-1") if err != nil { - t.Fatalf("Prepare() error = %v, want nil", err) + t.Fatal(err) } - - if prepared.PromptID != PromptID || prepared.PromptVersion != PromptVersion { - t.Fatalf("prepared prompt identity = %q %q, want %q %q", prepared.PromptID, prepared.PromptVersion, PromptID, PromptVersion) + correction := CorrectionRequest(CorrectionPromptID, "test-profile", "session-1", []string{"Use only candidate numbers in the supplied range.", "Preserve distinct entities."}) + if len(correction.Inputs) != 1 { + t.Fatal("correction regenerated fixed evidence") } - if prepared.SelectedProfileID != "semantic-reconciliation-test" { - t.Fatalf("selected profile = %q, want explicit test profile", prepared.SelectedProfileID) - } - if contract := prepared.OutputContract; contract.SchemaPath != "semantic_reconciliation_llm.v1.json" || contract.RepairAttempts != 1 { - t.Fatalf("output contract = %#v, want generic schema with one repair", contract) - } - if len(prepared.Messages) != 5 || prepared.Messages[0].Role != "system" { - t.Fatalf("prepared messages = %#v, want five ordered messages beginning with system", prepared.Messages) - } - if cache := prepared.Messages[2].CacheControl; cache == nil || cache.Type != promptkit.CacheControlEphemeral { - t.Fatalf("semantic policy cache control = %#v, want ephemeral", cache) - } - for _, index := range []int{0, 1, 3, 4} { - if prepared.Messages[index].CacheControl != nil { - t.Fatalf("message %d cache control = %#v, want nil", index, prepared.Messages[index].CacheControl) + var first promptkit.PreparedRun + for i, request := range []promptkit.RunRequest{initial, correction} { + handle, err := engine.PrepareExecution(context.Background(), request) + if err != nil { + t.Fatal(err) + } + prepared := handle.Details() + handle.Discard() + if prepared.SelectedProfileID != "test-profile" || prepared.SessionID != "session-1" { + t.Fatal("request selection lost") + } + if prepared.OutputContract.ValidationMode != promptkit.ValidationJSONSchema || prepared.StructuredOutput == nil { + t.Fatal("native response schema missing") + } + if i == 0 { + first = prepared + var system string + for _, message := range prepared.Messages { + if message.Role == "system" { + system += message.Content + } + } + for _, rule := range []string{"candidate_number_range", "not candidate numbers", "do not copy candidate names", "Preserve distinct entities"} { + if !strings.Contains(system, rule) { + t.Fatalf("missing enduring system principle %q", rule) + } + } + } else { + if !reflect.DeepEqual(first.OutputContract, prepared.OutputContract) || len(prepared.Messages) != 1 || prepared.Messages[0].Role != "user" { + t.Fatal("correction changed native contract or supplied more than a follow-up assignment") + } + text := prepared.Messages[0].Content + if !strings.Contains(text, "Use only candidate numbers") || !strings.Contains(text, "complete replacement proposal") { + t.Fatal("correction lost findings or assignment") + } + for _, material := range preparation.Materials() { + if strings.Contains(text, string(material)) { + t.Fatal("correction contains regenerated input material") + } + } } } - protocol := prepared.Messages[1].Content - for _, requirement := range []string{"candidate_number_range", "Return candidate numbers only", "do not copy candidate names", "start_unit_id", "not candidate numbers"} { - if !strings.Contains(protocol, requirement) { - t.Fatalf("protocol message = %q, want requirement %q", protocol, requirement) - } - } - if !strings.Contains(prepared.Messages[3].Content, `"candidate_number":1`) || strings.Contains(prepared.Messages[3].Content, `"windows"`) { - t.Fatalf("candidate message = %q, want only integer candidate material", prepared.Messages[3].Content) - } - if !strings.Contains(prepared.Messages[4].Content, `"windows"`) || strings.Contains(prepared.Messages[4].Content, `"candidate_number"`) { - t.Fatalf("transcript message = %q, want only transcript windows", prepared.Messages[4].Content) - } -} - -func TestAssetHashesAreDeterministicAndComplete(t *testing.T) { - firstPrompt, err := PromptHash() - if err != nil { - t.Fatal(err) - } - secondPrompt, err := PromptHash() - if err != nil { - t.Fatal(err) - } - schemaHash, err := SchemaHash() - if err != nil { - t.Fatal(err) - } - if firstPrompt == "" || firstPrompt != secondPrompt || schemaHash == "" || firstPrompt == schemaHash { - t.Fatalf("asset hashes = prompt %q/%q schema %q, want stable distinct hashes", firstPrompt, secondPrompt, schemaHash) - } -} - -func TestSharedPromptFilesExposeOnlyReusableCoreAssets(t *testing.T) { - first, err := SharedPromptFiles() - if err != nil { - t.Fatal(err) - } - second, err := SharedPromptFiles() - if err != nil { - t.Fatal(err) - } - wantNames := []string{"protocol.md", "candidates.md", "transcript-windows.md"} - gotNames := make([]string, len(first)) - for index, file := range first { - gotNames[index] = file.Name - if content, err := fs.ReadFile(file.FS, file.Path); err != nil || len(content) == 0 { - t.Fatalf("shared file %q = %q, %v; want readable content", file.Name, content, err) - } - } - if !reflect.DeepEqual(gotNames, wantNames) { - t.Fatalf("shared files = %#v, want narrow allowlist %#v", gotNames, wantNames) - } - first[0].Name = "changed.md" - if second[0].Name != "protocol.md" { - t.Fatalf("SharedPromptFiles() reused mutable descriptors: %#v", second) + if len(client.requests) != 0 { + t.Fatal("offline preparation called a provider") } } diff --git a/internal/framework/semanticreconcile/doc.go b/internal/framework/semanticreconcile/doc.go index 514b330d..c0fa786a 100644 --- a/internal/framework/semanticreconcile/doc.go +++ b/internal/framework/semanticreconcile/doc.go @@ -1,3 +1,4 @@ -// Package semanticreconcile prepares, executes, and validates bounded -// domain-neutral semantic reconciliation requests. +// Package semanticreconcile prepares fixed source-backed candidate material, +// builds native requests, and assesses and applies domain-neutral duplicate +// proposals. Typed owners execute through the pipeline producer helper. package semanticreconcile diff --git a/internal/framework/semanticreconcile/engine.go b/internal/framework/semanticreconcile/engine.go deleted file mode 100644 index 48528b3d..00000000 --- a/internal/framework/semanticreconcile/engine.go +++ /dev/null @@ -1,254 +0,0 @@ -package semanticreconcile - -import ( - "context" - "errors" - "fmt" - "strings" - - "gitea.maximumdirect.net/eric/notarius/internal/core/source" - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" - "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" -) - -// PromptSpec identifies the exact prompt selected by a reconciliation owner. -type PromptSpec struct { - ID string - Version string - SHA256 string -} - -// Validate rejects incomplete prompt identity and non-canonical digests. -func (spec PromptSpec) Validate() error { - if strings.TrimSpace(spec.ID) == "" { - return fmt.Errorf("semantic reconciliation prompt ID must not be empty") - } - if strings.TrimSpace(spec.Version) == "" { - return fmt.Errorf("semantic reconciliation prompt version must not be empty") - } - if err := validateSHA256(spec.SHA256); err != nil { - return fmt.Errorf("semantic reconciliation prompt digest: %w", err) - } - return nil -} - -// DefaultPromptSpec returns the identity of the core-owned generic prompt. -func DefaultPromptSpec() (PromptSpec, error) { - digest, err := PromptHash() - if err != nil { - return PromptSpec{}, err - } - return PromptSpec{ID: PromptID, Version: PromptVersion, SHA256: digest}, nil -} - -// Request contains one typed owner's source-backed reconciliation input. -type Request struct { - StageName string - Source *source.SourceDocument - Candidates []Candidate - ProfileID string - StructuredOutputRepairAttempts *int - SessionID string - Correction *contracts.SemanticCorrection -} - -// ResultDisposition classifies a provider-neutral reconciliation outcome. -type ResultDisposition uint8 - -const ( - Complete ResultDisposition = iota + 1 - RetryableInvalidStructuredOutput - RetryableDiscardedProposalGroups - SkippedInsufficientCandidates - SkippedLimitExceeded -) - -// Result owns the safe plan and neutral diagnostics from one call. -type Result struct { - disposition ResultDisposition - plan Plan - issues []Issue - discardedGroupCount int - candidateNumberRange CandidateNumberRange - candidateMappings []CandidateMapping - modelCandidate *contracts.ModelCandidate -} - -// Disposition returns the classified outcome. -func (result Result) Disposition() ResultDisposition { return result.disposition } - -// Plan returns an independently owned safe plan. -func (result Result) Plan() Plan { return result.planCopy() } - -// Issues returns an owned copy of stable proposal issues. -func (result Result) Issues() []Issue { return append([]Issue(nil), result.issues...) } - -// DiscardedGroupCount returns the number of excluded proposal groups. -func (result Result) DiscardedGroupCount() int { return result.discardedGroupCount } - -// CandidateNumberRange returns the exact request-local range used for this call. -func (result Result) CandidateNumberRange() CandidateNumberRange { - return result.candidateNumberRange -} - -// CandidateMappings returns the request-local number mapping used for this call. -func (result Result) CandidateMappings() []CandidateMapping { - return append([]CandidateMapping(nil), result.candidateMappings...) -} - -// CorrectionDetails returns bounded model-facing descriptions of the result's -// proposal issues using the exact candidate-number range for this call. -func (result Result) CorrectionDetails() ([]string, error) { - return CorrectionDetails(result.Issues(), result.candidateNumberRange) -} - -// CorrectionGuidance returns one bounded replacement request for this result. -func (result Result) CorrectionGuidance(additionalDetails ...string) (string, error) { - return CorrectionGuidance(result.Issues(), result.candidateNumberRange, additionalDetails...) -} - -// ModelCandidate returns an owned copy of the proposal response when a model -// completion produced this result. -func (result Result) ModelCandidate() *contracts.ModelCandidate { - candidate, err := contracts.CloneModelCandidate(result.modelCandidate) - if err != nil { - return nil - } - return candidate -} - -func (result Result) planCopy() Plan { - return Plan{groups: result.plan.Groups()} -} - -// Engine prepares bounded material, performs one structured completion, and -// classifies the deterministic assessment without applying it to typed values. -type Engine struct { - client contracts.StructuredLLMClient - prompt PromptSpec - schema llm.ResponseSchema - limits Limits -} - -// NewEngine constructs a reconciliation engine using the core response schema. -func NewEngine(client contracts.StructuredLLMClient, prompt PromptSpec, limits Limits) (*Engine, error) { - if client == nil { - return nil, fmt.Errorf("construct semantic reconciliation engine: LLM client must not be nil") - } - if err := prompt.Validate(); err != nil { - return nil, fmt.Errorf("construct semantic reconciliation engine: %w", err) - } - if err := limits.Validate(); err != nil { - return nil, fmt.Errorf("construct semantic reconciliation engine: %w", err) - } - schema, err := LoadResponseSchema() - if err != nil { - return nil, fmt.Errorf("construct semantic reconciliation engine: load response schema: %w", err) - } - return newEngine(client, prompt, schema, limits), nil -} - -func newEngine(client contracts.StructuredLLMClient, prompt PromptSpec, schema llm.ResponseSchema, limits Limits) *Engine { - return &Engine{client: client, prompt: prompt, schema: schema, limits: limits} -} - -// Reconcile prepares and assesses one request. Retryable semantic outcomes are -// returned as results; provider and transport failures remain errors. -func (engine *Engine) Reconcile(ctx context.Context, request Request) (Result, error) { - if err := engine.validate(); err != nil { - return Result{}, err - } - if ctx == nil { - return Result{}, fmt.Errorf("semantic reconciliation %q: context must not be nil", request.StageName) - } - if strings.TrimSpace(request.StageName) == "" { - return Result{}, fmt.Errorf("semantic reconciliation stage name must not be empty") - } - if request.Source == nil { - return Result{}, fmt.Errorf("semantic reconciliation %q: source document must not be nil", request.StageName) - } - if err := ctx.Err(); err != nil { - return Result{}, fmt.Errorf("semantic reconciliation %q: context error before preparation: %w", request.StageName, err) - } - - preparation, err := Prepare(request.Source, request.Candidates, engine.limits) - if err != nil { - return Result{}, fmt.Errorf("semantic reconciliation %q: prepare materials: %w", request.StageName, err) - } - result := Result{ - candidateNumberRange: preparation.CandidateNumberRange(), - candidateMappings: preparation.CandidateMappings(), - } - switch preparation.Disposition() { - case InsufficientCandidates: - result.disposition = SkippedInsufficientCandidates - return result, nil - case LimitExceeded: - result.disposition = SkippedLimitExceeded - return result, nil - case Ready: - default: - return Result{}, fmt.Errorf("semantic reconciliation %q: unknown preparation disposition %d", request.StageName, preparation.Disposition()) - } - - if err := ctx.Err(); err != nil { - return Result{}, fmt.Errorf("semantic reconciliation %q: context error before completion: %w", request.StageName, err) - } - correction, err := contracts.CloneSemanticCorrection(request.Correction) - if err != nil { - return Result{}, fmt.Errorf("semantic reconciliation %q: clone correction: %w", request.StageName, err) - } - var response ProposalResponse - completion, err := engine.client.CompleteStructured(ctx, contracts.StructuredCompletionRequest{ - StageName: request.StageName, - PromptID: engine.prompt.ID, - PromptVersion: engine.prompt.Version, - ProfileID: request.ProfileID, - SessionID: request.SessionID, - StructuredOutputRepairAttempts: request.StructuredOutputRepairAttempts, - Inputs: preparation.Materials(), - Correction: correction, - }, &response) - if err != nil { - if errors.Is(err, contracts.ErrInvalidStructuredOutput) { - result.disposition = RetryableInvalidStructuredOutput - return result, nil - } - return Result{}, fmt.Errorf("semantic reconciliation %q: complete structured output: %w", request.StageName, err) - } - candidate, err := contracts.NewModelCandidate(completion.Content, contracts.CorrectionProtocolSingleResponseV1) - if err != nil { - return Result{}, fmt.Errorf("semantic reconciliation %q: own model candidate: %w", request.StageName, err) - } - result.modelCandidate = candidate - - assessment := preparation.Assess(response) - result.plan = assessment.Plan() - result.issues = assessment.Issues() - result.discardedGroupCount = assessment.DiscardedGroupCount() - if result.discardedGroupCount > 0 { - result.disposition = RetryableDiscardedProposalGroups - } else { - result.disposition = Complete - } - return result, nil -} - -func (engine *Engine) validate() error { - if engine == nil { - return fmt.Errorf("semantic reconciliation engine must not be nil") - } - if engine.client == nil { - return fmt.Errorf("semantic reconciliation engine: LLM client must not be nil") - } - if err := engine.prompt.Validate(); err != nil { - return fmt.Errorf("semantic reconciliation engine: invalid construction state: %w", err) - } - if err := engine.limits.Validate(); err != nil { - return fmt.Errorf("semantic reconciliation engine: invalid construction state: %w", err) - } - if err := validateResponseSchemaIdentity(engine.schema); err != nil { - return fmt.Errorf("semantic reconciliation engine: invalid construction state: %w", err) - } - return nil -} diff --git a/internal/framework/semanticreconcile/engine_test.go b/internal/framework/semanticreconcile/engine_test.go index 08faa0e0..b3725fac 100644 --- a/internal/framework/semanticreconcile/engine_test.go +++ b/internal/framework/semanticreconcile/engine_test.go @@ -2,335 +2,162 @@ package semanticreconcile import ( "context" - "errors" - "fmt" "reflect" "strings" "testing" - "time" - "gitea.maximumdirect.net/eric/notarius/internal/core/source" - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" - "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" + "gitea.maximumdirect.net/eric/notarius/assets" + "go.maximumdirect.net/configkit" + "go.maximumdirect.net/promptkit" ) -func TestNewEngineValidatesConstruction(t *testing.T) { - prompt := testPromptSpec("a") - tests := []struct { - name string - client contracts.StructuredLLMClient - prompt PromptSpec - limits Limits - want string - }{ - {name: "nil client", prompt: prompt, limits: DefaultLimits(), want: "client"}, - {name: "empty prompt ID", client: &recordingReconciliationClient{}, prompt: PromptSpec{Version: "v1", SHA256: testDigest("a")}, limits: DefaultLimits(), want: "prompt ID"}, - {name: "empty prompt version", client: &recordingReconciliationClient{}, prompt: PromptSpec{ID: "prompt", SHA256: testDigest("a")}, limits: DefaultLimits(), want: "prompt version"}, - {name: "missing digest", client: &recordingReconciliationClient{}, prompt: PromptSpec{ID: "prompt", Version: "v1"}, limits: DefaultLimits(), want: "digest"}, - {name: "wrong digest algorithm", client: &recordingReconciliationClient{}, prompt: PromptSpec{ID: "prompt", Version: "v1", SHA256: "md5:" + strings.Repeat("a", 32)}, limits: DefaultLimits(), want: "sha256:"}, - {name: "non canonical digest", client: &recordingReconciliationClient{}, prompt: PromptSpec{ID: "prompt", Version: "v1", SHA256: "sha256:" + strings.Repeat("A", 64)}, limits: DefaultLimits(), want: "lowercase"}, - {name: "invalid limits", client: &recordingReconciliationClient{}, prompt: prompt, limits: Limits{}, want: "limits"}, - } - for _, test := range tests { - t.Run(test.name, func(t *testing.T) { - if _, err := NewEngine(test.client, test.prompt, test.limits); err == nil || !strings.Contains(err.Error(), test.want) { - t.Fatalf("NewEngine() error = %v, want %q", err, test.want) - } - }) - } - - defaultPrompt, err := DefaultPromptSpec() - if err != nil { - t.Fatal(err) - } - if defaultPrompt.ID != PromptID || defaultPrompt.Version != PromptVersion || defaultPrompt.SHA256 == "" { - t.Fatalf("DefaultPromptSpec() = %#v, want complete generic prompt identity", defaultPrompt) - } +type nativeReconciliationClient struct { + requests []promptkit.GenerateRequest + output string } -func TestEnginePropagatesRequestAndAssessesResponse(t *testing.T) { - client := &recordingReconciliationClient{responses: []ProposalResponse{{DuplicateGroups: []DuplicateGroup{{ - CandidateNumbers: []int{1, 2}, CanonicalCandidateNumber: 2, - }}}}} - engine := newTestEngine(t, client, DefaultLimits()) - request := readyEngineRequest() - request.ProfileID = " profile-as-resolved " - request.SessionID = " session-as-supplied " - correction, err := contracts.NewSemanticCorrection([]byte(`{"duplicate_groups":[]}`), "retain distinct candidates") - if err != nil { - t.Fatal(err) - } - request.Correction = correction - - result, err := engine.Reconcile(context.Background(), request) - if err != nil { - t.Fatalf("Reconcile() error = %v, want nil", err) - } - if result.Disposition() != Complete || result.DiscardedGroupCount() != 0 || len(result.Issues()) != 0 { - t.Fatalf("result = disposition %v discarded %d issues %#v", result.Disposition(), result.DiscardedGroupCount(), result.Issues()) - } - if got, want := result.CandidateNumberRange(), (CandidateNumberRange{First: 1, Last: 2}); got != want { - t.Fatalf("candidate number range = %#v, want %#v", got, want) - } - groups := result.Plan().Groups() - if len(groups) != 1 || !reflect.DeepEqual(groups[0].MemberPositions(), []int{0, 1}) || groups[0].CanonicalPosition() != 1 { - t.Fatalf("safe plan = %#v", groups) - } - if len(client.requests) != 1 { - t.Fatalf("completion calls = %d, want exactly one", len(client.requests)) - } - got := client.requests[0] - if got.StageName != request.StageName || got.PromptID != engine.prompt.ID || got.PromptVersion != engine.prompt.Version || got.ProfileID != request.ProfileID || got.SessionID != request.SessionID { - t.Fatalf("structured request = %#v, want exact routing values", got) - } - if !reflect.DeepEqual(got.Correction, correction) { - t.Fatalf("structured request correction = %#v, want %#v", got.Correction, correction) - } - if len(got.Inputs) != 2 || got.Inputs["candidates"].Name != "candidates" || got.Inputs["transcript"].Name != "transcript" || len(got.Vars) != 0 { - t.Fatalf("structured request inputs = %#v vars = %#v, want only candidate and transcript materials", got.Inputs, got.Vars) - } - candidate := result.ModelCandidate() - if candidate == nil || candidate.Protocol != contracts.CorrectionProtocolSingleResponseV1 || string(candidate.Response) != `{"duplicate_groups":[]}` { - t.Fatalf("model candidate = %#v, want exact owned completion response", candidate) - } +func (client *nativeReconciliationClient) Generate(_ context.Context, request promptkit.GenerateRequest) (*promptkit.GenerateResponse, error) { + client.requests = append(client.requests, request) + return &promptkit.GenerateResponse{Content: client.output}, nil } -func TestEngineClassifiesSemanticAndTransportOutcomes(t *testing.T) { - transportErr := errors.New("provider unavailable") - tests := []struct { - name string - response ProposalResponse - completion error - want ResultDisposition - wantDiscard int - wantIssues bool - wantCandidate bool - wantError error - }{ - {name: "empty groups complete", response: ProposalResponse{DuplicateGroups: []DuplicateGroup{}}, want: Complete, wantCandidate: true}, - {name: "discarded proposal retryable", response: ProposalResponse{DuplicateGroups: []DuplicateGroup{{CandidateNumbers: []int{1, 99}, CanonicalCandidateNumber: 1}}}, want: RetryableDiscardedProposalGroups, wantDiscard: 1, wantIssues: true, wantCandidate: true}, - {name: "invalid structured output retryable", completion: fmt.Errorf("decode response: %w", contracts.ErrInvalidStructuredOutput), want: RetryableInvalidStructuredOutput}, - {name: "transport failure", completion: transportErr, wantError: transportErr}, - } - for _, test := range tests { - t.Run(test.name, func(t *testing.T) { - client := &recordingReconciliationClient{responses: []ProposalResponse{test.response}, errors: []error{test.completion}} - result, err := newTestEngine(t, client, DefaultLimits()).Reconcile(context.Background(), readyEngineRequest()) - if test.wantError != nil { - if !errors.Is(err, test.wantError) || !strings.Contains(err.Error(), readyEngineRequest().StageName) { - t.Fatalf("Reconcile() error = %v, want contextual %v", err, test.wantError) - } - return - } - if err != nil { - t.Fatalf("Reconcile() error = %v, want nil", err) - } - if result.Disposition() != test.want || result.DiscardedGroupCount() != test.wantDiscard || (len(result.Issues()) > 0) != test.wantIssues { - t.Fatalf("result = disposition %v discarded %d issues %#v", result.Disposition(), result.DiscardedGroupCount(), result.Issues()) - } - if (result.ModelCandidate() != nil) != test.wantCandidate { - t.Fatalf("model candidate = %#v, want presence %t", result.ModelCandidate(), test.wantCandidate) - } - if len(client.requests) != 1 { - t.Fatalf("completion calls = %d, want one", len(client.requests)) - } - }) - } -} - -func TestEngineSkipsDeterministicOutcomesWithoutCompletion(t *testing.T) { - tests := []struct { - name string - request Request - limits Limits - want ResultDisposition - mappingLen int - }{ - {name: "insufficient candidates", request: engineRequestWithCandidateCount(1), limits: DefaultLimits(), want: SkippedInsufficientCandidates, mappingLen: 1}, - {name: "candidate limit", request: engineRequestWithCandidateCount(2), limits: Limits{ContextRadius: 0, MaximumCandidates: 1, MaximumMaterialBytes: 10000}, want: SkippedLimitExceeded, mappingLen: 2}, - {name: "material limit", request: engineRequestWithCandidateCount(2), limits: Limits{ContextRadius: 0, MaximumCandidates: 2, MaximumMaterialBytes: 1}, want: SkippedLimitExceeded, mappingLen: 2}, - } - for _, test := range tests { - t.Run(test.name, func(t *testing.T) { - client := &recordingReconciliationClient{} - result, err := newTestEngine(t, client, test.limits).Reconcile(context.Background(), test.request) - if err != nil { - t.Fatalf("Reconcile() error = %v, want nil", err) - } - if result.Disposition() != test.want || len(result.CandidateMappings()) != test.mappingLen { - t.Fatalf("result disposition = %v mappings = %#v", result.Disposition(), result.CandidateMappings()) - } - if result.ModelCandidate() != nil { - t.Fatalf("model candidate = %#v, want nil for no-call outcome", result.ModelCandidate()) - } - if len(client.requests) != 0 { - t.Fatalf("completion calls = %d, want zero", len(client.requests)) - } - }) - } -} - -func TestEngineRejectsInvalidInvocationAndHonorsCancellation(t *testing.T) { - request := readyEngineRequest() - client := &recordingReconciliationClient{} - engine := newTestEngine(t, client, DefaultLimits()) - - var nilEngine *Engine - if _, err := nilEngine.Reconcile(context.Background(), request); err == nil || !strings.Contains(err.Error(), "engine must not be nil") { - t.Fatalf("nil engine error = %v", err) - } - if _, err := (&Engine{}).Reconcile(context.Background(), request); err == nil || !strings.Contains(err.Error(), "client") { - t.Fatalf("zero engine error = %v", err) - } - invalid := newEngine(&recordingReconciliationClient{}, testPromptSpec("a"), llm.ResponseSchema{}, DefaultLimits()) - if _, err := invalid.Reconcile(context.Background(), request); err == nil || !strings.Contains(err.Error(), "invalid construction state") { - t.Fatalf("invalid construction error = %v", err) - } - if _, err := engine.Reconcile(nil, request); err == nil || !strings.Contains(err.Error(), "context") { - t.Fatalf("nil context error = %v", err) - } - withoutStage := request - withoutStage.StageName = " " - if _, err := engine.Reconcile(context.Background(), withoutStage); err == nil || !strings.Contains(err.Error(), "stage name") { - t.Fatalf("empty stage error = %v", err) - } - withoutSource := request - withoutSource.Source = nil - if _, err := engine.Reconcile(context.Background(), withoutSource); err == nil || !strings.Contains(err.Error(), "source document") { - t.Fatalf("nil source error = %v", err) - } - - canceled, cancel := context.WithCancel(context.Background()) - cancel() - if _, err := engine.Reconcile(canceled, request); !errors.Is(err, context.Canceled) || !strings.Contains(err.Error(), "before preparation") { - t.Fatalf("preparation cancellation error = %v", err) - } - if _, err := engine.Reconcile(&cancelBeforeCompletionContext{}, request); !errors.Is(err, context.Canceled) || !strings.Contains(err.Error(), "before completion") { - t.Fatalf("completion cancellation error = %v", err) - } - if len(client.requests) != 0 { - t.Fatalf("completion calls = %d, want zero for invalid and canceled invocations", len(client.requests)) - } -} - -func TestEngineCallsAreIndependentAndResultsAreOwned(t *testing.T) { - client := &recordingReconciliationClient{responses: []ProposalResponse{ - {DuplicateGroups: []DuplicateGroup{ - {CandidateNumbers: []int{1, 2}, CanonicalCandidateNumber: 1}, - {CandidateNumbers: []int{2, 99}, CanonicalCandidateNumber: 2}, - }}, - {DuplicateGroups: []DuplicateGroup{}}, - }} - engine := newTestEngine(t, client, DefaultLimits()) - first, err := engine.Reconcile(context.Background(), readyEngineRequest()) - if err != nil { - t.Fatal(err) - } - first.Plan().Groups()[0].memberPositions[0] = 99 - firstIssues := first.Issues() - firstIssues[0].Category = "changed" - firstMappings := first.CandidateMappings() - firstMappings[0].CandidatePosition = 99 - firstCandidate := first.ModelCandidate() - firstCandidate.Response[0] = 'x' - if first.Plan().Groups()[0].MemberPositions()[0] != 0 || first.Issues()[0].Category == "changed" || first.CandidateMappings()[0].CandidatePosition != 0 || string(first.ModelCandidate().Response) != `{"duplicate_groups":[]}` { - t.Fatal("result accessors exposed retained state") - } - - second, err := engine.Reconcile(context.Background(), readyEngineRequest()) - if err != nil { - t.Fatal(err) - } - if second.Disposition() != Complete || len(second.Plan().Groups()) != 0 || len(second.Issues()) != 0 || second.DiscardedGroupCount() != 0 || len(second.CandidateMappings()) != 2 || second.ModelCandidate() == nil { - t.Fatalf("second result retained prior call state: disposition %v plan %#v issues %#v discarded %d mappings %#v", second.Disposition(), second.Plan().Groups(), second.Issues(), second.DiscardedGroupCount(), second.CandidateMappings()) - } -} - -type recordingReconciliationClient struct { - requests []contracts.StructuredCompletionRequest - responses []ProposalResponse - errors []error - content []byte -} - -func (client *recordingReconciliationClient) CompleteStructured(_ context.Context, request contracts.StructuredCompletionRequest, output any) (contracts.StructuredCompletionResponse, error) { - snapshot, err := contracts.CloneStructuredCompletionRequest(request) - if err != nil { - return contracts.StructuredCompletionResponse{}, fmt.Errorf("clone recording request: %w", err) - } - client.requests = append(client.requests, snapshot) - index := len(client.requests) - 1 - if index < len(client.errors) && client.errors[index] != nil { - return contracts.StructuredCompletionResponse{}, client.errors[index] - } - response := ProposalResponse{DuplicateGroups: []DuplicateGroup{}} - if index < len(client.responses) { - response = cloneProposalResponse(client.responses[index]) - } - target, ok := output.(*ProposalResponse) - if !ok { - return contracts.StructuredCompletionResponse{}, fmt.Errorf("output type = %T", output) - } - *target = response - content := append([]byte(nil), client.content...) - if len(content) == 0 { - content = []byte(`{"duplicate_groups":[]}`) - } - return contracts.StructuredCompletionResponse{Content: content}, nil -} - -func cloneProposalResponse(response ProposalResponse) ProposalResponse { - cloned := ProposalResponse{DuplicateGroups: make([]DuplicateGroup, len(response.DuplicateGroups))} - for index, group := range response.DuplicateGroups { - cloned.DuplicateGroups[index] = DuplicateGroup{ - CandidateNumbers: append([]int(nil), group.CandidateNumbers...), CanonicalCandidateNumber: group.CanonicalCandidateNumber, - } - } - return cloned -} - -func newTestEngine(t *testing.T, client contracts.StructuredLLMClient, limits Limits) *Engine { +func newReconciliationEngine(t *testing.T, client promptkit.LLMClient) *promptkit.Engine { t.Helper() - engine, err := NewEngine(client, testPromptSpec("a"), limits) + type settings struct { + PromptKit promptkit.Settings `yaml:"promptkit"` + } + definition := promptkit.Configure(configkit.Definition[settings]{}, func(value *settings) *promptkit.Settings { return &value.PromptKit }) + filesystem := configkit.NewFilesystem("Notarius assets", assets.FS()) + result, err := configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("reconciliation fixture", []byte(`promptkit: + profiles: + - id: test-profile + endpoint: https://example.invalid/v1 + model: reconciliation-test-model + api_key_required: false +`))}, configkit.LayeredOptions[settings]{ + Definition: definition, + Underlays: []configkit.Underlay{ + promptkit.BundledOpenRouterUnderlay(), + {Inputs: []configkit.Input{{Source: filesystem.File("notarius.yml"), Imports: true, Filesystem: &configkit.FilesystemContext{FS: &filesystem, Root: "."}}}}, + }}) if err != nil { - t.Fatalf("NewEngine() error = %v", err) + t.Fatal(err) + } + engine, err := promptkit.NewFromConfig(result, promptkit.RuntimeConfig{}, promptkit.WithLLMClient(client)) + if err != nil { + t.Fatal(err) } return engine } -func testPromptSpec(digestCharacter string) PromptSpec { - return PromptSpec{ID: "test.semantic_reconciliation", Version: "v1", SHA256: testDigest(digestCharacter)} -} - -func testDigest(character string) string { return "sha256:" + strings.Repeat(character, 64) } - -func readyEngineRequest() Request { return engineRequestWithCandidateCount(2) } - -func engineRequestWithCandidateCount(count int) Request { - document := &source.SourceDocument{ID: "source", Units: []source.SourceUnit{ - {ID: 1, Kind: "speech", Text: "Mira arrived."}, - {ID: 2, Kind: "speech", Text: "The captain spoke."}, - }} - candidates := make([]Candidate, count) - for index := range candidates { - unitID := index%len(document.Units) + 1 - candidates[index] = Candidate{ - Label: fmt.Sprintf("candidate-%d", index+1), - SourceRefs: []source.SourceRef{{SourceID: document.ID, StartUnitID: unitID, EndUnitID: unitID}}, +func TestNativeRequestUsesFixedPreparedEvidenceAndRouting(t *testing.T) { + preparation := proposalPreparation(t) + before := preparation.Materials() + request, err := InitialRequest(preparation, PromptID, "test-profile", "session-1") + if err != nil { + t.Fatal(err) + } + if request.PromptID != PromptID || request.ProfileID != "test-profile" || request.SessionID != "session-1" { + t.Fatalf("routing = %#v", request) + } + client := &nativeReconciliationClient{output: `{"duplicate_groups":[{"candidate_numbers":[1,2],"canonical_candidate_number":2}]}`} + engine := newReconciliationEngine(t, client) + result, err := engine.Run(context.Background(), request) + if err != nil { + t.Fatal(err) + } + if result == nil || !result.Validation.IsValid { + t.Fatalf("invalid native result: %#v", result) + } + response, err := DecodeProposal(result.RawOutput) + if err != nil { + t.Fatal(err) + } + assessment := preparation.Assess(response) + if got, want := snapshotPlan(assessment.Plan()), []planGroupSnapshot{{members: []int{0, 2}, canonical: 2}}; !reflect.DeepEqual(got, want) { + t.Fatalf("plan = %#v, want %#v", got, want) + } + if len(client.requests) != 1 || client.requests[0].Prompt.SessionID != "session-1" || client.requests[0].Target.Model != "reconciliation-test-model" { + t.Fatal("native provider routing was not preserved") + } + var text string + for _, message := range client.requests[0].Prompt.Messages { + text += message.Content + } + for _, content := range before { + if !strings.Contains(text, string(content)) { + t.Fatal("request changed prepared evidence") } } - return Request{StageName: "test/normalize", Source: document, Candidates: candidates, ProfileID: "profile", SessionID: "session"} -} - -type cancelBeforeCompletionContext struct{ calls int } - -func (ctx *cancelBeforeCompletionContext) Deadline() (time.Time, bool) { return time.Time{}, false } -func (ctx *cancelBeforeCompletionContext) Done() <-chan struct{} { return nil } -func (ctx *cancelBeforeCompletionContext) Value(any) any { return nil } -func (ctx *cancelBeforeCompletionContext) Err() error { - ctx.calls++ - if ctx.calls > 1 { - return context.Canceled + returned := preparation.Materials() + returned[candidateInputName][0] = 'x' + request.Inputs[candidateInputName] = promptkit.Inline("caller mutation") + if !reflect.DeepEqual(preparation.Materials(), before) { + t.Fatal("request exposed retained preparation") + } +} + +func TestRequestConstructionRejectsUnreadyPreparation(t *testing.T) { + for _, preparation := range []Preparation{{}, {disposition: InsufficientCandidates}, {disposition: LimitExceeded}} { + request, err := InitialRequest(preparation, PromptID, "test-profile", "") + if err == nil || request.PromptID != "" { + t.Fatal("unready material produced a model request") + } + } +} + +func TestNativeStructuralFailureIsNotAReconciliationRetry(t *testing.T) { + client := &nativeReconciliationClient{output: `{"duplicate_groups":null}`} + engine := newReconciliationEngine(t, client) + request, err := InitialRequest(proposalPreparation(t), PromptID, "test-profile", "") + if err != nil { + t.Fatal(err) + } + // A test-selected native budget gives a terminal result without depending on + // the upstream default number of structural repair calls. + zero := 0 + request.Validation = &promptkit.OutputContractInput{ + Format: promptkit.FormatJSON, ValidationMode: promptkit.ValidationJSONSchema, + SchemaPath: "generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json", RepairAttempts: &zero, + } + result, err := engine.Run(context.Background(), request) + if err == nil && (result == nil || result.Validation.Status != promptkit.ValidationFailed || result.Validation.IsValid) { + t.Fatalf("native structural failure lost: %#v %v", result, err) + } + if len(client.requests) != 1 { + t.Fatalf("native test budget not respected: %d", len(client.requests)) + } +} + +func TestDecodeProposalReportsMalformedOutput(t *testing.T) { + if _, err := DecodeProposal("{"); err == nil { + t.Fatal("malformed JSON decoded") + } +} + +func TestRepeatedProposalsUseTheSameMappingWithoutPlanUnion(t *testing.T) { + preparation := proposalPreparation(t) + before := preparation.CandidateMappings() + first, err := DecodeProposal(`{"duplicate_groups":[{"candidate_numbers":[1,2],"canonical_candidate_number":1},{"candidate_numbers":[4,99],"canonical_candidate_number":4}]}`) + if err != nil { + t.Fatal(err) + } + earlier := preparation.Assess(first) + if earlier.DiscardedGroupCount() != 1 || len(earlier.Plan().Groups()) != 1 { + t.Fatalf("first assessment = %#v", earlier) + } + second, err := DecodeProposal(`{"duplicate_groups":[{"candidate_numbers":[4,5],"canonical_candidate_number":5}]}`) + if err != nil { + t.Fatal(err) + } + current := preparation.Assess(second) + if got, want := snapshotPlan(current.Plan()), []planGroupSnapshot{{members: []int{5, 6}, canonical: 6}}; !reflect.DeepEqual(got, want) { + t.Fatalf("current plan retained or remapped earlier groups: %#v", got) + } + if !reflect.DeepEqual(preparation.CandidateMappings(), before) { + t.Fatal("proposal assessment changed fixed handles") + } + if len(earlier.Plan().Groups()) != 1 || earlier.DiscardedGroupCount() != 1 { + t.Fatal("later proposal mutated earlier assessment") } - return nil } diff --git a/internal/framework/semanticreconcile/identity.go b/internal/framework/semanticreconcile/identity.go deleted file mode 100644 index 90046445..00000000 --- a/internal/framework/semanticreconcile/identity.go +++ /dev/null @@ -1,101 +0,0 @@ -package semanticreconcile - -import ( - "crypto/sha256" - "encoding/hex" - "fmt" - "strconv" - "strings" - - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" - "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" - "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" -) - -// Policy identifies the framework-owned reconciliation and assessment rules. -const Policy = "semantic_reconciliation.v3" - -var _ contracts.ManifestMetadataProvider = (*Engine)(nil) -var _ pipeline.CheckpointFingerprintProvider = (*Engine)(nil) - -// ManifestMetadata returns fresh, content-free identity for the complete core -// reconciliation mechanism. -func (engine *Engine) ManifestMetadata() map[string]any { - if engine == nil || engine.validate() != nil { - return nil - } - return map[string]any{ - "prompt_id": engine.prompt.ID, - "prompt_version": engine.prompt.Version, - "prompt_sha256": engine.prompt.SHA256, - "response_schema_key": string(engine.schema.Key), - "response_schema_id": engine.schema.ID, - "response_schema_name": engine.schema.Name, - "response_schema_version": engine.schema.Version, - "response_schema_sha256": engine.schema.SHA256, - "semantic_reconciliation_policy": Policy, - "semantic_reconciliation_limits": map[string]any{ - "context_radius": engine.limits.ContextRadius, - "maximum_candidates": engine.limits.MaximumCandidates, - "maximum_material_bytes": engine.limits.MaximumMaterialBytes, - }, - } -} - -// CheckpointFingerprints returns fresh canonical identities for prompt, -// schema, reconciliation policy, and the complete limit policy. -func (engine *Engine) CheckpointFingerprints() []pipeline.CheckpointFingerprint { - if engine == nil || engine.validate() != nil { - return nil - } - return []pipeline.CheckpointFingerprint{ - {Name: "prompt", Value: identityDigest(engine.prompt.ID, engine.prompt.Version, engine.prompt.SHA256)}, - {Name: "response_schema", Value: identityDigest(string(engine.schema.Key), engine.schema.ID, engine.schema.Version, engine.schema.Name, engine.schema.SHA256)}, - {Name: "semantic_reconciliation_policy", Value: Policy}, - {Name: "semantic_reconciliation_limits", Value: limitPolicyDigest(engine.limits)}, - } -} - -func limitPolicyDigest(limits Limits) string { - return identityDigest( - strconv.Itoa(limits.ContextRadius), - strconv.Itoa(limits.MaximumCandidates), - strconv.Itoa(limits.MaximumMaterialBytes), - ) -} - -func identityDigest(parts ...string) string { - hash := sha256.New() - for _, part := range parts { - _, _ = hash.Write([]byte(strconv.Itoa(len(part)))) - _, _ = hash.Write([]byte{':'}) - _, _ = hash.Write([]byte(part)) - } - return "sha256:" + hex.EncodeToString(hash.Sum(nil)) -} - -func validateResponseSchemaIdentity(schema llm.ResponseSchema) error { - if strings.TrimSpace(string(schema.Key)) == "" || strings.TrimSpace(schema.ID) == "" || strings.TrimSpace(schema.Version) == "" || strings.TrimSpace(schema.Name) == "" { - return fmt.Errorf("response schema identity must be complete") - } - if err := validateSHA256(schema.SHA256); err != nil { - return fmt.Errorf("response schema digest: %w", err) - } - return nil -} - -func validateSHA256(value string) error { - const prefix = "sha256:" - if !strings.HasPrefix(value, prefix) { - return fmt.Errorf("must use sha256: prefix") - } - hexValue := strings.TrimPrefix(value, prefix) - if len(hexValue) != sha256.Size*2 || hexValue != strings.ToLower(hexValue) { - return fmt.Errorf("must contain 64 lowercase hexadecimal characters") - } - decoded, err := hex.DecodeString(hexValue) - if err != nil || len(decoded) != sha256.Size { - return fmt.Errorf("must contain 64 lowercase hexadecimal characters") - } - return nil -} diff --git a/internal/framework/semanticreconcile/identity_test.go b/internal/framework/semanticreconcile/identity_test.go deleted file mode 100644 index 8699f210..00000000 --- a/internal/framework/semanticreconcile/identity_test.go +++ /dev/null @@ -1,93 +0,0 @@ -package semanticreconcile - -import ( - "testing" - - "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" - "gitea.maximumdirect.net/eric/notarius/internal/framework/pipeline" -) - -func TestEngineMetadataAndFingerprintsCoverCoreIdentity(t *testing.T) { - base := newTestEngine(t, &recordingReconciliationClient{}, DefaultLimits()) - metadata := base.ManifestMetadata() - for _, key := range []string{ - "prompt_id", "prompt_version", "prompt_sha256", - "response_schema_key", "response_schema_id", "response_schema_name", "response_schema_version", "response_schema_sha256", - "semantic_reconciliation_policy", "semantic_reconciliation_limits", - } { - if metadata[key] == nil || metadata[key] == "" { - t.Fatalf("metadata[%q] = %#v, want populated core identity", key, metadata[key]) - } - } - limits, ok := metadata["semantic_reconciliation_limits"].(map[string]any) - if !ok || len(limits) != 3 || limits["context_radius"] == nil || limits["maximum_candidates"] == nil || limits["maximum_material_bytes"] == nil { - t.Fatalf("limit metadata = %#v, want complete limits", metadata["semantic_reconciliation_limits"]) - } - fingerprints := base.CheckpointFingerprints() - wantNames := []string{"prompt", "response_schema", "semantic_reconciliation_policy", "semantic_reconciliation_limits"} - if len(fingerprints) != len(wantNames) { - t.Fatalf("fingerprints = %#v, want required categories", fingerprints) - } - for index, want := range wantNames { - if fingerprints[index].Name != want || fingerprints[index].Value == "" { - t.Fatalf("fingerprint %d = %#v, want %q with value", index, fingerprints[index], want) - } - } - - metadata["prompt_id"] = "changed" - limits["context_radius"] = -1 - fingerprints[0].Name = "changed" - if got := base.ManifestMetadata(); got["prompt_id"] == "changed" || got["semantic_reconciliation_limits"].(map[string]any)["context_radius"] == -1 { - t.Fatalf("ManifestMetadata() exposed retained state: %#v", got) - } - if got := base.CheckpointFingerprints(); got[0].Name == "changed" { - t.Fatalf("CheckpointFingerprints() exposed retained state: %#v", got) - } -} - -func TestCoreFingerprintsChangeWithBehavioralIdentity(t *testing.T) { - base := newTestEngine(t, &recordingReconciliationClient{}, DefaultLimits()) - baseFingerprints := base.CheckpointFingerprints() - - promptChanged, err := NewEngine(&recordingReconciliationClient{}, testPromptSpec("b"), DefaultLimits()) - if err != nil { - t.Fatal(err) - } - assertOnlyFingerprintChanged(t, baseFingerprints, promptChanged.CheckpointFingerprints(), "prompt") - - schema, err := LoadResponseSchema() - if err != nil { - t.Fatal(err) - } - schema.SHA256 = testDigest("b") - schemaChanged := newEngine(&recordingReconciliationClient{}, base.prompt, schema, DefaultLimits()) - assertOnlyFingerprintChanged(t, baseFingerprints, schemaChanged.CheckpointFingerprints(), "response_schema") - - limits := DefaultLimits() - limits.ContextRadius++ - limitsChanged, err := NewEngine(&recordingReconciliationClient{}, base.prompt, limits) - if err != nil { - t.Fatal(err) - } - assertOnlyFingerprintChanged(t, baseFingerprints, limitsChanged.CheckpointFingerprints(), "semantic_reconciliation_limits") -} - -func TestInvalidEngineIdentityHasNoMetadataOrFingerprints(t *testing.T) { - invalid := newEngine(&recordingReconciliationClient{}, testPromptSpec("a"), llm.ResponseSchema{}, DefaultLimits()) - if invalid.ManifestMetadata() != nil || invalid.CheckpointFingerprints() != nil { - t.Fatalf("invalid engine exposed identity: metadata %#v fingerprints %#v", invalid.ManifestMetadata(), invalid.CheckpointFingerprints()) - } -} - -func assertOnlyFingerprintChanged(t *testing.T, before, after []pipeline.CheckpointFingerprint, changedName string) { - t.Helper() - if len(before) != len(after) { - t.Fatalf("fingerprint counts differ: %#v %#v", before, after) - } - for index := range before { - changed := before[index] != after[index] - if changed != (before[index].Name == changedName) { - t.Fatalf("fingerprint %q change = %t, want only %q changed\nbefore: %#v\nafter: %#v", before[index].Name, changed, changedName, before, after) - } - } -} diff --git a/internal/framework/semanticreconcile/preparation.go b/internal/framework/semanticreconcile/preparation.go index 248eba6d..b9b0d422 100644 --- a/internal/framework/semanticreconcile/preparation.go +++ b/internal/framework/semanticreconcile/preparation.go @@ -1,20 +1,16 @@ package semanticreconcile import ( - "crypto/sha256" - "encoding/hex" "encoding/json" "fmt" "sort" "gitea.maximumdirect.net/eric/notarius/internal/core/source" - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" ) const ( candidateInputName = "candidates" transcriptInputName = "transcript" - jsonMediaType = "application/json" ) var defaultLimits = Limits{ @@ -89,7 +85,7 @@ type Preparation struct { disposition Disposition candidateNumberRange CandidateNumberRange mappings []CandidateMapping - materials contracts.LLMInputSet + materials map[string][]byte } // Disposition returns the preparation outcome. @@ -110,8 +106,15 @@ func (preparation Preparation) CandidateNumberRange() CandidateNumberRange { // Materials returns independently owned candidate and transcript materials. // It is empty unless Disposition returns Ready. -func (preparation Preparation) Materials() contracts.LLMInputSet { - return preparation.materials.Clone() +func (preparation Preparation) Materials() map[string][]byte { + if preparation.materials == nil { + return nil + } + materials := make(map[string][]byte, len(preparation.materials)) + for name, content := range preparation.materials { + materials[name] = append([]byte(nil), content...) + } + return materials } type sourceRange struct { @@ -242,9 +245,9 @@ func Prepare(document *source.SourceDocument, candidates []Candidate, limits Lim } result.disposition = Ready - result.materials = contracts.LLMInputSet{ - candidateInputName: newInputMaterial(candidateInputName, candidateContent), - transcriptInputName: newInputMaterial(transcriptInputName, transcriptContent), + result.materials = map[string][]byte{ + candidateInputName: candidateContent, + transcriptInputName: transcriptContent, } return result, nil } @@ -412,14 +415,3 @@ func appendWithinLimit(content []byte, maximumBytes int, parts ...[]byte) ([]byt } return content, true } - -func newInputMaterial(name string, content []byte) contracts.LLMInputMaterial { - digest := sha256.Sum256(content) - return contracts.NewLLMInputMaterial( - name, - jsonMediaType, - content, - "sha256:"+hex.EncodeToString(digest[:]), - "", - ) -} diff --git a/internal/framework/semanticreconcile/preparation_test.go b/internal/framework/semanticreconcile/preparation_test.go index a30336f7..fd64f741 100644 --- a/internal/framework/semanticreconcile/preparation_test.go +++ b/internal/framework/semanticreconcile/preparation_test.go @@ -1,8 +1,6 @@ package semanticreconcile import ( - "crypto/sha256" - "encoding/hex" "encoding/json" "math" "reflect" @@ -67,16 +65,12 @@ func TestPrepareBuildsContiguousCandidatesAndOwnedSourceContext(t *testing.T) { t.Fatal("transcript material is missing") } for name, material := range materials { - if material.Name != name || material.MediaType != "application/json" || material.OriginURI != "" || material.SizeBytes != int64(len(material.Content)) { - t.Fatalf("material %q metadata = %#v", name, material) - } - digest := sha256.Sum256(material.Content) - if want := "sha256:" + hex.EncodeToString(digest[:]); material.Digest != want { - t.Fatalf("material %q digest = %q, want %q", name, material.Digest, want) + if !json.Valid(material) { + t.Fatalf("material %q is not valid JSON", name) } } - candidateContent := append([]byte(nil), materials[candidateInputName].Content...) + candidateContent := append([]byte(nil), materials[candidateInputName]...) var candidatePayload candidateInput if err := json.Unmarshal(candidateContent, &candidatePayload); err != nil { t.Fatal(err) @@ -102,7 +96,7 @@ func TestPrepareBuildsContiguousCandidatesAndOwnedSourceContext(t *testing.T) { t.Fatalf("model-facing candidate fields = %#v", candidate) } } - combined := string(materials[candidateInputName].Content) + string(materials[transcriptInputName].Content) + combined := string(materials[candidateInputName]) + string(materials[transcriptInputName]) for _, forbidden := range []string{document.ID, "application_entity_id", "private-entity-id", `"candidate_id"`, `"candidate_ids"`, `"canonical_candidate_id"`} { if strings.Contains(combined, forbidden) { t.Fatalf("model material leaked %q: %s", forbidden, combined) @@ -110,7 +104,7 @@ func TestPrepareBuildsContiguousCandidatesAndOwnedSourceContext(t *testing.T) { } var transcript transcriptInput - if err := json.Unmarshal(materials[transcriptInputName].Content, &transcript); err != nil { + if err := json.Unmarshal(materials[transcriptInputName], &transcript); err != nil { t.Fatal(err) } if len(transcript.Windows) != 1 || len(transcript.Windows[0].Units) != len(document.Units) { @@ -132,11 +126,11 @@ func TestPrepareBuildsContiguousCandidatesAndOwnedSourceContext(t *testing.T) { candidates[0].SourceRefs[0].StartUnitID = 40 document.Units[1].Metadata["speaker"].(map[string]any)["name"] = "changed" - if got := preparation.Materials()[candidateInputName].Content; !reflect.DeepEqual(got, candidateContent) { + if got := preparation.Materials()[candidateInputName]; !reflect.DeepEqual(got, candidateContent) { t.Fatalf("candidate material changed through caller input: %s", got) } var retained transcriptInput - if err := json.Unmarshal(preparation.Materials()[transcriptInputName].Content, &retained); err != nil { + if err := json.Unmarshal(preparation.Materials()[transcriptInputName], &retained); err != nil { t.Fatal(err) } if got := retained.Windows[0].Units[1].Metadata["speaker"].(map[string]any)["name"]; got != "Mira" { @@ -147,10 +141,10 @@ func TestPrepareBuildsContiguousCandidatesAndOwnedSourceContext(t *testing.T) { returnedMappings[0].CandidatePosition = 99 returnedMaterials := preparation.Materials() candidateMaterial := returnedMaterials[candidateInputName] - candidateMaterial.Content[0] = '[' + candidateMaterial[0] = '[' returnedMaterials[candidateInputName] = candidateMaterial delete(returnedMaterials, transcriptInputName) - if preparation.CandidateMappings()[0].CandidatePosition != 0 || !json.Valid(preparation.Materials()[candidateInputName].Content) || len(preparation.Materials()) != 2 { + if preparation.CandidateMappings()[0].CandidatePosition != 0 || !json.Valid(preparation.Materials()[candidateInputName]) || len(preparation.Materials()) != 2 { t.Fatal("preparation accessors exposed retained data") } } @@ -207,7 +201,7 @@ func TestPrepareFiltersUnsafeCandidatesAndCoalescesAdjacentWindows(t *testing.T) t.Fatalf("CandidateNumberRange() after filtering = %#v, want %#v", got, want) } var transcript transcriptInput - if err := json.Unmarshal(preparation.Materials()[transcriptInputName].Content, &transcript); err != nil { + if err := json.Unmarshal(preparation.Materials()[transcriptInputName], &transcript); err != nil { t.Fatal(err) } if len(transcript.Windows) != 1 || len(transcript.Windows[0].Units) != 2 || transcript.Windows[0].Units[0].ID != 3 || transcript.Windows[0].Units[1].ID != 8 { @@ -302,7 +296,7 @@ func TestPrepareStopsRenderingContextWhenMaterialLimitIsExceeded(t *testing.T) { if err != nil || base.Disposition() != Ready { t.Fatalf("Prepare(base) = disposition %v, error %v", base.Disposition(), err) } - candidateBytes := len(base.Materials()[candidateInputName].Content) + candidateBytes := len(base.Materials()[candidateInputName]) document.Units[1].Metadata = cycle limited, err := Prepare(document, candidates, Limits{ @@ -330,7 +324,7 @@ func TestPrepareAcceptsExactCombinedByteLimitAndSkipsOneOver(t *testing.T) { t.Fatalf("Prepare(base) = disposition %v, error %v", base.Disposition(), err) } materials := base.Materials() - totalBytes := len(materials[candidateInputName].Content) + len(materials[transcriptInputName].Content) + totalBytes := len(materials[candidateInputName]) + len(materials[transcriptInputName]) exactLimits := baseLimits exactLimits.MaximumMaterialBytes = totalBytes diff --git a/internal/framework/semanticreconcile/proposal.go b/internal/framework/semanticreconcile/proposal.go index e068d82d..29431d65 100644 --- a/internal/framework/semanticreconcile/proposal.go +++ b/internal/framework/semanticreconcile/proposal.go @@ -1,12 +1,10 @@ package semanticreconcile import ( + "encoding/json" "fmt" "sort" "strings" - "unicode/utf8" - - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" ) // ProposalResponse is the complete private structured response contract. @@ -14,6 +12,17 @@ type ProposalResponse struct { DuplicateGroups []DuplicateGroup `json:"duplicate_groups"` } +// DecodeProposal reads an already structurally validated native response. +// Native execution errors and failed validation must be handled before this +// function; decoding never requests another structural repair or execution. +func DecodeProposal(output string) (ProposalResponse, error) { + var response ProposalResponse + if err := json.Unmarshal([]byte(output), &response); err != nil { + return ProposalResponse{}, fmt.Errorf("decode semantic reconciliation proposal: %w", err) + } + return response, nil +} + // DuplicateGroup proposes supplied request-local candidate numbers that may // denote one entity and identifies one supplied member as canonical. type DuplicateGroup struct { @@ -121,39 +130,6 @@ func CorrectionDetails(issues []Issue, numberRange CandidateNumberRange) ([]stri return details, nil } -// CorrectionGuidance builds one bounded request for a complete corrected -// proposal. Additional details let a typed owner append a domain rule without -// weakening or duplicating the shared protocol guidance. -func CorrectionGuidance(issues []Issue, numberRange CandidateNumberRange, additionalDetails ...string) (string, error) { - details, err := CorrectionDetails(issues, numberRange) - if err != nil { - return "", err - } - for _, detail := range additionalDetails { - if !utf8.ValidString(detail) { - return "", fmt.Errorf("semantic reconciliation additional correction detail has invalid UTF-8") - } - detail = strings.TrimSpace(detail) - if detail == "" { - return "", fmt.Errorf("semantic reconciliation additional correction detail must not be blank") - } - details = append(details, detail) - } - if len(details) == 0 { - return "", fmt.Errorf("semantic reconciliation correction guidance requires at least one detail") - } - - parts := make([]string, 0, len(details)+2) - parts = append(parts, "The previous semantic-duplicate proposal was invalid.") - parts = append(parts, details...) - parts = append(parts, "Return one complete corrected JSON response that follows the original instructions; do not return a patch or commentary.") - guidance := strings.Join(parts, " ") - if len(guidance) > contracts.MaxNormalizeRetryCorrectionGuidanceBytes { - return "", fmt.Errorf("semantic reconciliation correction guidance exceeds maximum length") - } - return guidance, nil -} - func validateCorrectionRange(numberRange CandidateNumberRange) error { if numberRange.First != 1 || numberRange.Last < 2 { return fmt.Errorf("semantic reconciliation correction candidate-number range must start at 1 and include at least two candidates") @@ -251,8 +227,8 @@ func (assessment Assessment) DiscardedGroupCount() int { return assessment.discardedGroupCount } -// RetryRequired reports whether any response group was discarded. -func (assessment Assessment) RetryRequired() bool { +// HasDiscardedGroups reports whether the proposal contains unsafe groups. +func (assessment Assessment) HasDiscardedGroups() bool { return assessment.discardedGroupCount > 0 } diff --git a/internal/framework/semanticreconcile/proposal_test.go b/internal/framework/semanticreconcile/proposal_test.go index 6eb40c70..dcfbec6f 100644 --- a/internal/framework/semanticreconcile/proposal_test.go +++ b/internal/framework/semanticreconcile/proposal_test.go @@ -6,7 +6,6 @@ import ( "testing" "gitea.maximumdirect.net/eric/notarius/internal/core/source" - "gitea.maximumdirect.net/eric/notarius/internal/framework/contracts" ) func TestAssessProducesAStableOriginalPositionPlan(t *testing.T) { @@ -23,8 +22,8 @@ func TestAssessProducesAStableOriginalPositionPlan(t *testing.T) { if got := snapshotPlan(assessment.Plan()); !reflect.DeepEqual(got, want) { t.Fatalf("plan = %#v, want %#v", got, want) } - if assessment.DiscardedGroupCount() != 0 || assessment.RetryRequired() || len(assessment.Issues()) != 0 { - t.Fatalf("assessment diagnostics = discarded %d, retry %t, issues %#v", assessment.DiscardedGroupCount(), assessment.RetryRequired(), assessment.Issues()) + if assessment.DiscardedGroupCount() != 0 || assessment.HasDiscardedGroups() || len(assessment.Issues()) != 0 { + t.Fatalf("assessment diagnostics = discarded count %d, has unsafe groups %t, issues %#v", assessment.DiscardedGroupCount(), assessment.HasDiscardedGroups(), assessment.Issues()) } reordered := preparation.Assess(ProposalResponse{DuplicateGroups: []DuplicateGroup{ @@ -36,8 +35,8 @@ func TestAssessProducesAStableOriginalPositionPlan(t *testing.T) { } empty := preparation.Assess(ProposalResponse{}) - if len(empty.Plan().Groups()) != 0 || len(empty.Issues()) != 0 || empty.DiscardedGroupCount() != 0 || empty.RetryRequired() { - t.Fatalf("empty assessment = plan %#v, issues %#v, discarded %d, retry %t", empty.Plan().Groups(), empty.Issues(), empty.DiscardedGroupCount(), empty.RetryRequired()) + if len(empty.Plan().Groups()) != 0 || len(empty.Issues()) != 0 || empty.DiscardedGroupCount() != 0 || empty.HasDiscardedGroups() { + t.Fatalf("empty assessment = plan %#v, issues %#v, discarded count %d, has unsafe groups %t", empty.Plan().Groups(), empty.Issues(), empty.DiscardedGroupCount(), empty.HasDiscardedGroups()) } } @@ -52,7 +51,7 @@ func TestIssueDetailsPreservesIssueOrder(t *testing.T) { } } -func TestCorrectionGuidanceCoversEveryIssueCategoryWithoutExposingInternalLabels(t *testing.T) { +func TestCorrectionDetailsCoverEveryIssueCategoryWithoutExposingInternalLabels(t *testing.T) { numberRange := CandidateNumberRange{First: 1, Last: 8} if len(issueCorrectionProse) != len(allIssueCategories) { t.Fatalf("correction prose entries = %d, categories = %d", len(issueCorrectionProse), len(allIssueCategories)) @@ -74,12 +73,9 @@ func TestCorrectionGuidanceCoversEveryIssueCategoryWithoutExposingInternalLabels if err != nil { t.Fatalf("CorrectionDetails() error = %v", err) } - guidance, err := CorrectionGuidance(issues, numberRange) - if err != nil { - t.Fatalf("CorrectionGuidance() error = %v", err) - } - if len(details) != len(allIssueCategories)+1 || !strings.Contains(guidance, "Duplicate group 1") || !strings.Contains(guidance, "candidate-number range 1 through 8") || !strings.Contains(guidance, "start_unit_id") || !strings.Contains(guidance, "complete corrected JSON response") || len(guidance) > contracts.MaxNormalizeRetryCorrectionGuidanceBytes { - t.Fatalf("correction details = %#v guidance = %q", details, guidance) + guidance := strings.Join(details, " ") + if len(details) != len(allIssueCategories)+1 || !strings.Contains(guidance, "Duplicate group 1") || !strings.Contains(guidance, "candidate-number range 1 through 8") || !strings.Contains(guidance, "start_unit_id") { + t.Fatalf("correction details = %#v", details) } for _, category := range allIssueCategories { if strings.Contains(guidance, string(category)) { @@ -103,10 +99,6 @@ func TestCorrectionDetailsDeduplicatesAndBoundsAffectedGroupLists(t *testing.T) if len(details) != 2 || !strings.Contains(details[0], "additional affected group") || strings.Count(details[0], "Duplicate groups") != 1 || !strings.Contains(details[1], "source positions") { t.Fatalf("CorrectionDetails() = %#v, want one bounded grouped detail and one namespace reminder", details) } - guidance, err := CorrectionGuidance(issues, numberRange) - if err != nil || len(guidance) > contracts.MaxNormalizeRetryCorrectionGuidanceBytes { - t.Fatalf("CorrectionGuidance() = %q, %v", guidance, err) - } } func TestCorrectionDetailsRejectsUnknownOrInvalidIssues(t *testing.T) { @@ -145,8 +137,8 @@ func TestAssessRejectsEveryUnsafeLocalGroupShape(t *testing.T) { for _, test := range tests { t.Run(test.name, func(t *testing.T) { assessment := preparation.Assess(ProposalResponse{DuplicateGroups: []DuplicateGroup{test.group}}) - if len(assessment.Plan().Groups()) != 0 || assessment.DiscardedGroupCount() != 1 || !assessment.RetryRequired() { - t.Fatalf("assessment = plan %#v, discarded %d, retry %t", assessment.Plan().Groups(), assessment.DiscardedGroupCount(), assessment.RetryRequired()) + if len(assessment.Plan().Groups()) != 0 || assessment.DiscardedGroupCount() != 1 || !assessment.HasDiscardedGroups() { + t.Fatalf("assessment = plan %#v, discarded count %d, has unsafe groups %t", assessment.Plan().Groups(), assessment.DiscardedGroupCount(), assessment.HasDiscardedGroups()) } if !hasIssue(assessment.Issues(), 0, test.category) { t.Fatalf("issues = %#v, want category %q", assessment.Issues(), test.category) @@ -166,8 +158,8 @@ func TestAssessDiscardsEveryOverlappingGroupAndRetainsIndependentGroups(t *testi if got := snapshotPlan(assessment.Plan()); !reflect.DeepEqual(got, wantPlan) { t.Fatalf("plan = %#v, want %#v", got, wantPlan) } - if assessment.DiscardedGroupCount() != 2 || !assessment.RetryRequired() { - t.Fatalf("discarded = %d, retry = %t", assessment.DiscardedGroupCount(), assessment.RetryRequired()) + if assessment.DiscardedGroupCount() != 2 || !assessment.HasDiscardedGroups() { + t.Fatalf("discarded count = %d, has unsafe groups = %t", assessment.DiscardedGroupCount(), assessment.HasDiscardedGroups()) } issues := assessment.Issues() if len(issues) != 2 || !hasIssue(issues, 0, IssueOverlappingMember) || !hasIssue(issues, 1, IssueOverlappingMember) { @@ -182,8 +174,8 @@ func TestAssessDiscardsEveryOverlappingGroupAndRetainsIndependentGroups(t *testi if got := snapshotPlan(invalidAndSafe.Plan()); !reflect.DeepEqual(got, wantPlan) { t.Fatalf("plan with independent invalid group = %#v, want %#v", got, wantPlan) } - if invalidAndSafe.DiscardedGroupCount() != 1 || !invalidAndSafe.RetryRequired() || !hasIssue(invalidAndSafe.Issues(), 0, IssueMemberUnknown) { - t.Fatalf("invalid-and-safe assessment = discarded %d, retry %t, issues %#v", invalidAndSafe.DiscardedGroupCount(), invalidAndSafe.RetryRequired(), invalidAndSafe.Issues()) + if invalidAndSafe.DiscardedGroupCount() != 1 || !invalidAndSafe.HasDiscardedGroups() || !hasIssue(invalidAndSafe.Issues(), 0, IssueMemberUnknown) { + t.Fatalf("invalid-and-safe assessment = discarded count %d, has unsafe groups %t, issues %#v", invalidAndSafe.DiscardedGroupCount(), invalidAndSafe.HasDiscardedGroups(), invalidAndSafe.Issues()) } } diff --git a/internal/framework/semanticreconcile/requests.go b/internal/framework/semanticreconcile/requests.go new file mode 100644 index 00000000..82bfe88e --- /dev/null +++ b/internal/framework/semanticreconcile/requests.go @@ -0,0 +1,34 @@ +package semanticreconcile + +import ( + "fmt" + "strings" + + "go.maximumdirect.net/promptkit" +) + +const PromptID = "notarius/generic.semantic_reconciliation" +const CorrectionPromptID = "notarius/generic.semantic_reconciliation.repair" + +// InitialRequest selects a native prompt and copies already prepared evidence. +// The owner prepares once and retains the same Preparation for every proposal. +// Deterministic skips and preparation limits do not create synthetic requests. +func InitialRequest(preparation Preparation, promptID, profileID, sessionID string) (promptkit.RunRequest, error) { + if preparation.Disposition() != Ready { + return promptkit.RunRequest{}, fmt.Errorf("semantic reconciliation materials are not ready for execution") + } + inputs := make(map[string]promptkit.ArtifactRef, len(preparation.materials)) + for name, content := range preparation.materials { + inputs[name] = promptkit.Inline(string(content)) + } + return promptkit.RunRequest{PromptID: promptID, ProfileID: profileID, SessionID: sessionID, Inputs: inputs}, nil +} + +// CorrectionRequest supplies only findings. Native coordination retains source +// windows, candidate handles, and prior proposals from the original exchange. +func CorrectionRequest(promptID, profileID, sessionID string, guidance []string) promptkit.RunRequest { + return promptkit.RunRequest{ + PromptID: promptID, ProfileID: profileID, SessionID: sessionID, + Inputs: map[string]promptkit.ArtifactRef{"guidance": promptkit.Inline(strings.Join(guidance, "\n\n"))}, + } +} diff --git a/internal/framework/semanticreconcile/schema.go b/internal/framework/semanticreconcile/schema.go deleted file mode 100644 index 2e7c1afc..00000000 --- a/internal/framework/semanticreconcile/schema.go +++ /dev/null @@ -1,41 +0,0 @@ -package semanticreconcile - -import ( - "fmt" - "io/fs" - - rootassets "gitea.maximumdirect.net/eric/notarius/assets" - "gitea.maximumdirect.net/eric/notarius/internal/framework/llm" -) - -const ( - ResponseSchemaKey = llm.ResponseSchemaKey("semantic_reconciliation_llm") - ResponseSchemaID = "notarius.generic.semantic_reconciliation.llm" - ResponseSchemaName = "notarius_semantic_reconciliation_llm_v1" - SchemaVersion = "v1" - SchemaAssetPath = "schemas/semantic_reconciliation_llm.v1.json" -) - -func assetFS() (fs.FS, error) { - assets, err := fs.Sub(rootassets.FS(), "generic/normalize/deduplication") - if err != nil { - return nil, fmt.Errorf("scope semantic reconciliation assets: %w", err) - } - return assets, nil -} - -// LoadResponseSchema returns the private request-local integer proposal -// contract. It is separate from every durable artifact schema. -func LoadResponseSchema() (llm.ResponseSchema, error) { - assets, err := assetFS() - if err != nil { - return llm.ResponseSchema{}, err - } - return llm.LoadResponseSchema(assets, llm.ResponseSchemaDefinition{ - Key: ResponseSchemaKey, - ID: ResponseSchemaID, - Version: SchemaVersion, - Name: ResponseSchemaName, - AssetPath: SchemaAssetPath, - }) -} diff --git a/internal/framework/semanticreconcile/schema_test.go b/internal/framework/semanticreconcile/schema_test.go index 027ca083..4bd5acc2 100644 --- a/internal/framework/semanticreconcile/schema_test.go +++ b/internal/framework/semanticreconcile/schema_test.go @@ -3,38 +3,17 @@ package semanticreconcile import ( "bytes" "encoding/json" + "io/fs" "reflect" - "strings" "testing" + "gitea.maximumdirect.net/eric/notarius/assets" + "github.com/santhosh-tekuri/jsonschema/v6" ) -func TestResponseSchemaMetadataAndOwnership(t *testing.T) { - schema, err := LoadResponseSchema() - if err != nil { - t.Fatal(err) - } - if schema.Key != ResponseSchemaKey || schema.ID != ResponseSchemaID || schema.Version != SchemaVersion || schema.Name != ResponseSchemaName { - t.Fatalf("schema metadata = %#v", schema) - } - if !json.Valid(schema.JSONSchema) || !strings.HasPrefix(schema.SHA256, "sha256:") { - t.Fatalf("schema content metadata = %#v", schema) - } - - first := append([]byte(nil), schema.JSONSchema...) - schema.JSONSchema[0] = '[' - loadedAgain, err := LoadResponseSchema() - if err != nil { - t.Fatal(err) - } - if !bytes.Equal(loadedAgain.JSONSchema, first) || !json.Valid(loadedAgain.JSONSchema) { - t.Fatal("LoadResponseSchema() exposed shared schema content") - } -} - func TestResponseSchemaAcceptsOnlyTheIntegerProposalShape(t *testing.T) { - schema, err := LoadResponseSchema() + schema, err := fs.ReadFile(assets.FS(), "generic/normalize/deduplication/schemas/semantic_reconciliation_llm.v1.json") if err != nil { t.Fatal(err) } @@ -66,7 +45,7 @@ func TestResponseSchemaAcceptsOnlyTheIntegerProposalShape(t *testing.T) { if err != nil { t.Fatal(err) } - err = validateAgainstSchema(content, schema.JSONSchema) + err = validateAgainstSchema(content, schema) if (err == nil) != test.valid { t.Fatalf("schema validation error = %v, want valid=%t", err, test.valid) } @@ -74,11 +53,11 @@ func TestResponseSchemaAcceptsOnlyTheIntegerProposalShape(t *testing.T) { } content := []byte(`{"duplicate_groups":[{"candidate_numbers":[1,2],"canonical_candidate_number":2}]}`) - if err := validateAgainstSchema(content, schema.JSONSchema); err != nil { + if err := validateAgainstSchema(content, schema); err != nil { t.Fatal(err) } - var response ProposalResponse - if err := json.Unmarshal(content, &response); err != nil { + response, err := DecodeProposal(string(content)) + if err != nil { t.Fatal(err) } want := ProposalResponse{DuplicateGroups: []DuplicateGroup{{CandidateNumbers: []int{1, 2}, CanonicalCandidateNumber: 2}}}