diff --git a/doc.go b/doc.go index 37beb6f..0e1d8e4 100644 --- a/doc.go +++ b/doc.go @@ -4,17 +4,17 @@ // Applications construct an [Engine] with [NewEngine], select ConfigKit // sources for prompts, profiles, and backends, and // call [Engine.InspectConfiguration], [Engine.InspectPrompt], -// [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.ListProfiles], -// [Engine.ListPrompts], [Engine.Prepare], [Engine.PrepareExecution], -// [Engine.Run], or [Engine.RunPrepared]. Concrete registries, repositories, +// [Engine.InspectRequirements], [Engine.InspectProfile], [Engine.InspectBackend], +// [Engine.ListProfiles], [Engine.ListPrompts], [Engine.Prepare], +// [Engine.PrepareExecution], [Engine.Run], or [Engine.RunPrepared]. Concrete registries, repositories, // validators, and the built-in OpenAI-compatible client remain internal // implementation details. // // # Concurrency and ownership // // An Engine supports concurrent InspectConfiguration, InspectPrompt, -// InspectRequirements, InspectProfile, ListProfiles, ListPrompts, Prepare, -// PrepareExecution, Run, and RunPrepared calls. Engine-local backend policies +// InspectRequirements, InspectProfile, InspectBackend, ListProfiles, ListPrompts, +// Prepare, PrepareExecution, Run, and RunPrepared calls. Engine-local backend policies // bound admitted Run and RunPrepared calls and model generations where // configured, while different backend pools and unlimited backends continue // independently. An injected [LLMClient] or [ArtifactReader] can therefore @@ -23,7 +23,8 @@ // ConfigKit captures the selected configuration when NewEngine constructs an // Engine. Prepare, PrepareExecution, and Run copy request maps, slices, pointer // values, and JSON-compatible extra parameters before using them. InspectPrompt, -// InspectRequirements, and InspectProfile return copied inspection values. +// InspectRequirements, InspectProfile, and InspectBackend return copied +// inspection values. // ListProfiles and ListPrompts return caller-owned identity slices. // Returned values and values passed to extension interfaces are likewise // isolated from engine state. @@ -56,17 +57,22 @@ // [GenerateResponse], [ExecutionTargetPresence], and the string value types // used by those values. // -// Construction, inspection, handle, and error values, including [Config], +// Resource inspection results support direct JSON and YAML encoding. +// [PromptInspection], [ProfileInspection], [BackendInspection], and their nested +// values define field names, nesting, and omission of absent optional fields. +// Formatting belongs to the selected encoder. +// +// Other construction, inspection, handle, and error values, including [Config], // [ConfigurationSources], [ConfigurationInspection], [BackendConfig], // [ProfileConfig], [RunRequest], -// [ArtifactRef], [ExecutionTargetOverride], [ProfileInspection], -// [PromptIdentity], [PromptInputDefinition], [PromptInspection], +// [ArtifactRef], [ExecutionTargetOverride], +// [PromptIdentity], [PromptInputDefinition], // [RequirementInspectionRequest], [RequirementInspection], [PreparedExecution], // [CapacityError], [GenerationError], [RetryExhaustedError], and // [ExecutionEvent], do not have stable JSON // representations. Direct API keys are nevertheless excluded from JSON for // every public value. - +// // Provider-derived [GenerationError] accessor values are untrusted and can // contain sensitive request or schema fragments. Applications must apply their // own disclosure policy before logging, displaying, or returning them. diff --git a/docs/consumers/configuration-migration.md b/docs/consumers/configuration-migration.md index d98321f..11acbf5 100644 --- a/docs/consumers/configuration-migration.md +++ b/docs/consumers/configuration-migration.md @@ -135,8 +135,10 @@ Replace former maps passed to `BackendSource` in the same way, setting each inspection paths now address list indexes, for example `configkit.Keys("profiles").Index(0).Key("model")`. Configuration inspection and diffs expose resolved values, recorded normalization and provenance. -`InspectProfile` additionally applies backend completion; request preparation -can apply further overrides, so the views are not promised to be identical. +`InspectProfile` reports the selected resolved profile without backend completion. +Use `Prepare` or `PreparedExecution.Details` for completed request settings, +including backend defaults and request overrides; see the +[resource inspection guidance](pkg-promptkit.md#inspect-a-profile-before-prompt-work). Remove `PromptVersion` and `PromptIdentity.Version` uses and the corresponding `prompt_version` JSON members. Prompt definition hashes are opaque equality diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 296b22d..ccf8196 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -20,11 +20,22 @@ in the reviewed implementation. The resource-oriented profile result and changed post-handoff null fallback are deliberately selected compatibility changes, not accidental regressions. +Review evidence below describes the pre-remediation implementation. Completion +markers record the subsequent corrections. + ## Findings ### R1. Reconcile Remaining Inspection Contract Documentation [P2] -**Status:** Open. **Affected stages:** 1, 11, and final reconciliation in 12. +**Status:** Complete. **Affected stages:** 1, 11, and final reconciliation in 12. + +Completion: package GoDoc now describes the resource JSON/YAML contract and +includes backend inspection in its orientation/ownership summary. A blank +comment separator that hid most of the rendered package overview was repaired. +The migration guide now distinguishes resolved profile inspection from completed +request settings and links to the current consumer guidance. Rendered `go doc`, +current-documentation checks, local links, and whitespace were verified; no +runtime behavior or published release note changed. **Locations:**