promptkit/docs/roadmap/responsibility-simplification.md

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. Findings 1–7 are selected for remediation; finding 8 selects preservation of runtime input behavior. The selected implementation and combined final validation are complete.

The work began from the f660b6e decision baseline and production audit baseline 1ff6d77. The audit owns historical evidence and decision rationale; this document owns the selected target and delivery scope. The implementation plan records implementation and validation. The older audit remediation describes an earlier completed sprint; its previous plan is retained in Git history, not the current implementation plan.

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

The following sections record the accepted work and its rationale. The target above is implemented; final checks are recorded in the implementation plan rather than inferred from the audit's baseline tests.

Resolved Targets And Direct Wire Construction

Audit findings: 1–2.

At the audit baseline, the LLM adapter stored constructor-level endpoint/model defaults that engine assembly never supplied, and built an intermediate root wire struct before encoding.

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 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 remains responsible for output syntax and schema checks. Use its existing prepared-validation plans for both checks in smoke inference: 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.

Acceptance and detachment have distinct responsibilities across captured backend/profile lookup, prepared details, execution results, injected-client and repair requests, and smoke reports. The target removes redundant traversals across those paths together, rather than moving a copy into another helper. The implementation plan records the corresponding ownership inventory.

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: 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. 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, model-client, runner, and source/validation 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. The implementation plan records the focused and combined checks performed on the delivered changes. No significant product decisions remain open. Release selection/publication and retirement of the older completed audit documents are separate work from this roadmap.