Make GoDoc the public API contract

public_contract_test.go

@@ -26,6 +26,30 @@ func TestPreparedRunJSONOmitsZeroTimingValues(t *testing.T) {
 	}
 }
 
+func TestPreparedRunJSONTimingRoundTrips(t *testing.T) {
+	start := time.Date(2026, time.July, 29, 12, 0, 0, 0, time.UTC)
+	prepared := promptkit.PreparedRun{
+		PromptID:   "prompt",
+		StartTime:  start,
+		EndTime:    start.Add(1250 * time.Millisecond),
+		DurationMS: 1250,
+	}
+
+	payload, err := json.Marshal(prepared)
+	if err != nil {
+		t.Fatalf("marshal prepared run: %v", err)
+	}
+	var decoded promptkit.PreparedRun
+	if err := json.Unmarshal(payload, &decoded); err != nil {
+		t.Fatalf("unmarshal prepared run: %v", err)
+	}
+	if decoded.DurationMS != prepared.DurationMS ||
+		!decoded.StartTime.Equal(prepared.StartTime) ||
+		!decoded.EndTime.Equal(prepared.EndTime) {
+		t.Fatalf("timing values did not round trip: got %#v, want %#v", decoded, prepared)
+	}
+}
+
 func TestRunResultJSONUsesMillisecondsAndRoundTrips(t *testing.T) {
 	start := time.Date(2026, time.July, 29, 12, 0, 0, 0, time.UTC)
 	result := promptkit.RunResult{
@@ -74,6 +98,36 @@ func TestRunResultJSONUsesMillisecondsAndRoundTrips(t *testing.T) {
 	}
 }
 
+func TestEngineValidationIsSinglePass(t *testing.T) {
+	client := &fakeLLMClient{
+		response: &promptkit.GenerateResponse{Content: "not-json"},
+	}
+	engine := newContractEngineWithOptions(t, frameworkSchemaDir, promptkit.WithLLMClient(client))
+
+	result, err := engine.Run(context.Background(), promptkit.RunRequest{
+		PromptID: frameworkMarkdownSummaryPromptID,
+		Inputs: map[string]promptkit.ArtifactRef{
+			"transcript": promptkit.Inline("Rin opens the gate."),
+			"glossary":   promptkit.Inline("gate: A guarded passage."),
+		},
+		Validation: &promptkit.OutputContract{
+			Format:         promptkit.FormatJSON,
+			ValidationMode: promptkit.ValidationJSON,
+			RepairAttempts: 3,
+		},
+	})
+	if err != nil {
+		t.Fatalf("run with failed content validation: %v", err)
+	}
+	if result.Validation.Status != promptkit.ValidationFailed ||
+		result.Validation.RepairAttempts != 0 {
+		t.Fatalf("expected failed single-pass validation, got %#v", result.Validation)
+	}
+	if len(client.requests) != 1 {
+		t.Fatalf("expected one model generation, got %d", len(client.requests))
+	}
+}
+
 func TestRepeatedOptionsUseLastValueInEachCategory(t *testing.T) {
 	profile := promptkit.Profile{ID: "profile", Endpoint: "http://example.test/v1", Model: "model"}