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](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 [implementation plan](implementation.md) owns the
ordered stages and validation for this work. The older
[audit remediation](audit-remediation.md) 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

### 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.

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](../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 significant product decisions remain open. Release selection/publication and
retirement of the older completed audit documents are separate work from this
roadmap.