Define the responsibility simplification roadmap
This commit is contained in:
224
docs/roadmap/responsibility-simplification.md
Normal file
224
docs/roadmap/responsibility-simplification.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user