Implement Phase 9 structured LLM adapter spike

internal/framework/contracts/contracts.go

@@ -14,7 +14,7 @@ import (
 
 // StructuredLLMClient provides provider-agnostic structured completion.
 type StructuredLLMClient interface {
-	CompleteStructured(ctx context.Context, req StructuredCompletionRequest) (StructuredCompletionResponse, error)
+	CompleteStructured(ctx context.Context, req StructuredCompletionRequest, out any) (StructuredCompletionResponse, error)
 }
 
 // TranscriptModule is the minimal contract for framework-integrated modules.
@@ -35,12 +35,18 @@ type Validator interface {
 type StructuredCompletionRequest struct {
 	StageName      string          `json:"stage_name"`
 	Messages       []LLMMessage    `json:"messages"`
+	Model          string          `json:"model,omitempty"`
 	ResponseSchema json.RawMessage `json:"response_schema,omitempty"`
 }
 
 // StructuredCompletionResponse is a transport-neutral structured completion response payload.
 type StructuredCompletionResponse struct {
-	Content json.RawMessage `json:"content"`
+	Content          json.RawMessage `json:"content"`
+	Provider         string          `json:"provider,omitempty"`
+	Model            string          `json:"model,omitempty"`
+	PromptTokens     int             `json:"prompt_tokens,omitempty"`
+	CompletionTokens int             `json:"completion_tokens,omitempty"`
+	TotalTokens      int             `json:"total_tokens,omitempty"`
 }
 
 // LLMMessage is a minimal chat message shape for LLM prompts.

internal/framework/contracts/contracts_test.go

@@ -13,9 +13,15 @@ import (
 
 type fakeLLMClient struct{}
 
-func (f *fakeLLMClient) CompleteStructured(ctx context.Context, req StructuredCompletionRequest) (StructuredCompletionResponse, error) {
+func (f *fakeLLMClient) CompleteStructured(ctx context.Context, req StructuredCompletionRequest, out any) (StructuredCompletionResponse, error) {
 	_ = ctx
 	_ = req
+	if out != nil {
+		switch target := out.(type) {
+		case *map[string]any:
+			*target = map[string]any{"ok": true}
+		}
+	}
 	return StructuredCompletionResponse{Content: json.RawMessage(`{"ok":true}`)}, nil
 }