diff --git a/docs/roadmap/responsibility-simplification.md b/docs/roadmap/responsibility-simplification.md new file mode 100644 index 0000000..5a2d6bd --- /dev/null +++ b/docs/roadmap/responsibility-simplification.md @@ -0,0 +1,224 @@ +# Responsibility Simplification Roadmap + +## Purpose And Status + +Simplify PromptKit's internal machinery by removing unused accommodations, +redundant representations, and repeated acceptance work while preserving the +library's substantive feature set and selected ownership boundaries. + +This roadmap captures the target state and work arising from the accepted +[responsibility audit](audit/A1-responsibility.md). Findings 1–7 are selected +for remediation; finding 8 selects preservation of runtime input behavior. +All significant decisions are settled. Implementation is pending. + +The current baseline is `f660b6e`. The production code remains at the audited +`1ff6d77` baseline; subsequent commits record the audit and accepted decisions. +The audit owns evidence and decision rationale; this document owns the selected +target and delivery scope. The older [audit remediation](audit-remediation.md) +and its completed implementation plan describe an earlier sprint, not this work. +A separate implementation plan will define prompt-sized stages for this scope. + +## Targeted End State + +PromptKit retains its public facade, ConfigKit composition boundary, captured +configuration, generation coordination, and existing consumer extension points. +Within those boundaries: + +- The built-in client consumes resolved targets without its own unused + endpoint/model fallback settings and builds one root provider payload. +- Prompt/profile lookup and rendering consume captured configuration directly, + without alternate uncaptured workflows maintained for private fixtures. +- Output validation uses the existing prepared-plan lifecycle throughout, + including both syntax and schema checks in smoke diagnostics. +- Already accepted values are detached when ownership requires it, rather than + repeatedly revalidated merely to make a copy. +- Executable preparation retains one private, redacted metadata snapshot, with + separate execution-only state and one outward details projection/copy. +- Schema acceptance is governed by the decoder/compiler and the selected + self-contained-schema rule, without additional copier-derived tree budgets. +- Runtime provider-value acceptance, limits, and current copying semantics + remain unchanged. + +The intended benefit is fewer execution paths, traversals, retained duplicate +graphs, and incidental error branches. This does not establish allocation, +throughput, complexity, or numerical-precision guarantees. + +## Selected Work + +### Resolved Targets And Direct Wire Construction + +**Audit findings:** 1–2. + +The [LLM adapter](../../internal/llm/openai_compatible_client.go) currently stores +constructor-level endpoint/model defaults that engine assembly never supplies. +It also creates a root wire struct solely to project it into the map actually +encoded for transport. + +Retire those constructor settings, stored fallback state, and fallback branches. +Backend/profile/request resolution remains the owner of target selection. Keep +checks needed to encode and dispatch the selected target, and preserve HTTP +client ownership, timeouts, authentication, and request preparation. + +Construct the root wire payload directly from the resolved generation request. +Typed nested message, content-block, cache-control, and schema-envelope values +can remain where useful. Preserve optional-control omission and explicit-zero +presence, session IDs, structured output, reserved-field checks, extension-field +flattening, and private dispatch evidence. This is removal of an intermediate +representation, not a new serializer or replacement settings-resolution layer. + +Fixtures that currently place defaults on an internal client should instead +provide resolved request targets. Retain meaningful wire and invalid-target +coverage without preserving the deleted fallback mechanism. + +### Captured Lookup And Rendering Only + +**Audit finding:** 3. + +Production [engine assembly](../../internal/engine/engine.go) already supplies +the captured configuration repository and compiled renderer. Align the private +lookup contracts with the captured operations actually consumed, retaining +narrow metadata queries rather than loading entire definitions for inspection. + +Retire optional-capability probes, fallback full-definition/profile loads, +invocation-time definition hashing, and the renderer's uncaptured parsing path. +Definition hashes and templates remain supplied by configuration capture. +Keep per-call template cloning and request-function binding, which protect +captured templates from request-specific mutation. + +Migrate fixtures to captured templates/metadata using the existing compiler or +real in-memory configuration. Preserve meaningful renderer and inspection +behavior rather than reconstructing a second production workflow inside test +helpers. Convenient no-repair runner construction and useful external-boundary +doubles need not disappear merely because they are test conveniences. + +### One Output-Validation Lifecycle + +**Audit finding:** 4. + +The [validation component](../../internal/validate/standard_validator.go) +remains responsible for output syntax and schema checks. Use its existing +prepared-validation plans for both checks in +[smoke inference](../../internal/usecase/smoke_inference_case.go): a JSON-only +plan for syntax and a schema plan for conformance. The JSON-only plan requires +no schema I/O or compilation. Schema evaluation follows successful syntax +validation; invalid syntax leaves schema conformance unevaluated. Preserve +existing cancellation handling and neutral diagnostic facts, including valid +JSON scalars that fail the diagnostic schema. + +Retire the standalone direct-validation interface, concrete direct methods, +and redundant on-demand schema-loading callbacks after their smoke caller is +migrated. Meaningful source, schema, and cancellation cases move to prepared +validation. Shared instance validation and source-specific root loading remain. +Do not preserve the removed interface through a test-only reimplementation. + +This deliberately supersedes the earlier selection to retain the private direct +workflow and its decode-before-schema-I/O behavior. It does not change public +`ValidateRequest`, request preflight, repair policy, or eager schema preparation. +No composite validator or diagnostic framework is needed. + +### Acceptance, Detachment, And Prepared Snapshot Ownership + +**Audit findings:** 5–6, with finding 8's preservation decision. + +Plan these changes together. For affected paths, establish where values are +accepted, whether they can subsequently be mutated, and where they cross into +caller/client-owned mutable state. A small ownership inventory in the +implementation plan is sufficient. Include captured backend/profile lookup, +prepared details, execution results, injected-client and repair requests, and +smoke reports; do not optimize one path by moving its extra copy into another. + +Keep validation at actual input-acceptance boundaries. For previously accepted +values, use existing trusted detachment where a mutable copy is needed and +share or transfer private values where ownership permits. Remove redundant +validation/error plumbing only when the relevant acceptance and mutation paths +justify doing so. A blanket replacement of validating copies is not the target. +Infallible projection should not acquire fallible-copy behavior or hide a +copying failure behind an empty result. + +Executable preparation should retain one immutable, credential-redacted +metadata snapshot shared by details and the execution payload. Direct +credentials, observer callbacks, retry settings, and validation resources remain +separate execution-only state with their existing lifecycle. Remove the current +payload-cleanup write into metadata before sharing it. Public details still +receive an independent mutable projection and remain available after execution +or discard; eliminating the internal copy before that projection must not expose +borrowed internal values to callers. + +Preserve prepared-handle identity, single claim/discard synchronization, source +freezing, credential privacy, and injected-client ownership. Retain current +runtime provider-value acceptance and limits, supported number/container forms, +and type/nil behavior. Runtime values do not become ConfigKit inputs merely to +reuse source restrictions. The existing trusted and validating walkers may +remain distinct; a configurable reflection or ownership framework is not needed. + +### Schema Copying Without An Incidental Resource Policy + +**Audit finding:** 7. + +Remove the additional schema-document depth/node rejection inherited from +`jsonvalue.Copy` during structured-output capture and prepared-details copying. +Schema detachment remains necessary; runtime provider-value budgets remain +unchanged. The decoder/compiler and the existing self-contained submission +checks continue to own schema acceptance. + +Retain source-specific schema loading, containment behavior, supported reference +and dialect handling, completeness checks, and outward mutation isolation. +Update tests and internal descriptions that currently sustain the copier-derived +schema rejection. A schema otherwise accepted by those owners should not fail +solely because an ownership copy uses runtime provider-value limits. + +This intentionally broadens acceptance of schemas rejected only by that copier. +It does not promise unlimited resources, stack safety, extra precision, provider +acceptance, or provider enforcement, and does not introduce a new schema budget. + +## Preserved Boundaries And Scope + +Follow [ADR 0001](../adr/0001-configuration-boundary.md): ConfigKit owns +composition up to its final handoff; PromptKit interprets final domain values. +Configuration history remains an explicit operator-inspection capability, not +an execution validation phase. + +The audit's retained-machinery analysis remains applicable. In particular, +preserve the public/internal facade and needed ownership copies, artifact-reader +defensive copying, separate admission and active permits, prepared-handle +lifecycle, template request isolation, schema root-source handling, HTTP +evidence/deadline behavior, and operation-owner error classification. + +This work does not require dependency upgrades, upstream publication, new public +extension points, changes to supported template syntax, new retries or limits, +capacity-manager redesign, or release-tooling changes. Equivalent private names +and package-local organization remain implementation choices. Additional +contract changes should be surfaced rather than inferred from this cleanup. + +## Tests And Documentation + +Follow the [testing policy](../policy/testing.md). Keep meaningful behavior +coverage and migrate fixtures to the surviving production paths. Remove tests +that exist only to sustain deleted accommodations; retain or consolidate their +useful wire, source, cancellation, ownership, and error-boundary protection. + +Use focused offline checks during implementation, race-enabled validation for +changed shared-state/ownership paths, and representative public preparation, +execution, repair, and diagnostic coverage. Reuse existing tests where they +protect the relevant behavior. Neither exact allocation assertions nor a new +benchmark or recurring release gate is required to establish this refactor. + +Update affected GoDoc and the [internal component overview](../internal/overview.md), +[model-client](../internal/llm.md), [runner](../internal/runner.md), and +[source/validation](../internal/sources.md) descriptions when behavior lands. +Consumer and format guidance should record the removed incidental schema +restriction where relevant, without implying new resource or provider promises. +Other public API/wire behavior remains governed by its existing canonical owners. + +## Completion + +Completion means findings 1–7 have their selected changes, finding 8's runtime +behavior is preserved, and relevant behavioral checks and canonical documentation +match the result. Caller review should confirm that retired private workflows +and duplicate state are actually gone rather than renamed or relocated. + +The audit's test results describe the original baseline, not evidence of the +replacement implementation. Record actual implementation outcomes separately. +No additional product decision or evidence-gathering phase is required before +preparing the staged plan. Release selection/publication and retirement of the +older completed audit documents are separate work from this roadmap.