225 lines
12 KiB
Markdown
225 lines
12 KiB
Markdown
# 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.
|