Make GoDoc the public API contract

docs/roadmap/documentation.md

@@ -57,47 +57,15 @@ that is currently ambiguous.
 - [x] Confirm the supported JSON Schema dialect and reference boundaries,
   including whether remote references are allowed.
 
-The resolved contract is:
+The selected exported API contracts are implemented and tested. Their durable
+definitions now belong to the root package declarations and GoDoc.
 
-- `RunRequest.Metadata` had no observable purpose and has been removed from the
-  public and internal request values.
-- One engine supports overlapping `Prepare` and `Run` calls. Built-in
-  collaborators satisfy that contract; injected collaborators may be called
-  concurrently and therefore share responsibility for concurrency safety.
-- Options are applied in order. Within each prompt-source, profile-source,
-  in-memory-profile, schema-source, model-client, or artifact-reader category,
-  the last non-nil valid option replaces the earlier value for that category.
-  An invalid earlier option still makes construction fail.
-- The supported JSON values are `PreparedRun`, `RunResult`, `Artifact`,
-  `ExecutionTarget`, `OutputContract`, `ValidationResult`, `TokenUsage`,
-  `RenderedPrompt`, `RenderedMessage`, `CacheControl`,
-  `StructuredOutputSpec`, `StructuredOutputJSONSpec`, `GenerateRequest`,
-  `GenerateResponse`, `ExecutionTargetPresence`, and the public string value
-  types used by them. Construction inputs such as `Config`, `RunRequest`,
-  `ArtifactRef`, `ExecutionTargetOverride`, `Profile`, and
-  `OpenAICompatibleProfileConfig` do not have stable JSON representations.
-  Request-scoped API keys remain excluded from JSON as a security guarantee,
-  including on otherwise unsupported construction values.
-- JSON timestamps use `time.Time`'s RFC 3339 representation and are omitted
-  when zero. Both prepared and completed run durations use integer
-  milliseconds in `duration_ms` and are omitted when zero. A prepared duration
-  measures preparation only; a run-result duration measures the complete run,
-  including its preparation, generation, and validation.
-- Run IDs, prompt hashes, rendered-prompt hashes, input hashes, and artifact
-  hashes are non-empty correlation or equality values where produced. Their
-  spelling, length, character set, and algorithm are opaque and not stable
-  formats.
-- The built-in transport timeout defaults to 10 minutes. A zero or negative
-  `Config.Timeout` selects that default. A supplied HTTP client's positive
-  timeout takes precedence; its zero or negative timeout inherits the positive
-  configured timeout or the default. These transport semantics are independent
-  of caller cancellation and per-generation timeout settings.
-- JSON Schema uses Draft 2020-12; omission of `$schema` selects that dialect
-  and an explicit different dialect is rejected. Same-document fragment
-  references are supported. Relative references may load other schema
-  documents only within a configured directory or `fs.FS` schema root.
-  A single-file schema source supports only references contained in that
-  document. Absolute, escaping, and remote references are not allowed.
+One format-level decision remains here until Stage 5 moves it to the framework
+format reference: JSON Schema uses Draft 2020-12, with that dialect selected
+when `$schema` is omitted. Same-document fragments and relative references
+contained by a directory or `fs.FS` schema root are supported. A single-file
+source supports only references contained in that document. Absolute,
+escaping, and remote references are rejected.
 
 **Gate:** Each question has an explicit answer backed by existing behavior or
 by an accepted implementation change and proportionate tests. No later stage
@@ -108,21 +76,21 @@ should invent a contract merely to fill a documentation gap.
 Strengthen the root package declarations so `go doc` is sufficient to
 understand exact public behavior without relying on internal documents.
 
-- [ ] Add useful field-level GoDoc to configuration, request, profile,
+- [x] Add useful field-level GoDoc to configuration, request, profile,
   execution-target, result, artifact, validation, structured-output, and model
   client values.
-- [ ] Document required fields and nil, empty, and zero-value semantics.
-- [ ] Document override, replacement, profile-precedence, and copy-ownership
+- [x] Document required fields and nil, empty, and zero-value semantics.
+- [x] Document override, replacement, profile-precedence, and copy-ownership
   behavior where it belongs to the exported API.
-- [ ] Document credential inputs, redaction, and the values intentionally
+- [x] Document credential inputs, redaction, and the values intentionally
   excluded from serialization.
-- [ ] Give each public error sentinel an accurate comment and document the
+- [x] Give each public error sentinel an accurate comment and document the
   supported `errors.Is` relationships.
-- [ ] Document engine concurrency and option-composition behavior selected in
+- [x] Document engine concurrency and option-composition behavior selected in
   Stage 1.
-- [ ] Document serialization, time, run-ID, and hash semantics selected in
+- [x] Document serialization, time, run-ID, and hash semantics selected in
   Stage 1.
-- [ ] Review constructor, option, extension-interface, `Prepare`, and `Run`
+- [x] Review constructor, option, extension-interface, `Prepare`, and `Run`
   GoDoc for complete failure and cancellation expectations.
 
 Update the [consumer guide](../consumers/pkg-promptkit.md) to summarize and link