base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Record final validation and repair audit links

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-05 20:19:06 +00:00
parent 96c619f7d4
commit 5ee602cc4b
13 changed files with 168 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/roadmap/audit/01-correctness.md
View File

@@ -30,9 +30,9 @@ availability or acceptance of arbitrary JSON Schema features.
**Priority:** P2. Confirmed data-conversion defect.
**Code:** [providerValueForMapping](../../../provider_values.go:51), used by
[ProfileSource](../../../profiles.go:33) and
[BackendSource](../../../backends.go:100).
**Code:** [providerValueForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/provider_values.go#L51), used by
[ProfileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/profiles.go#L33) and
[BackendSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/backends.go#L100).
**Circumstances:** A caller supplies a valid `json.Number` in provider
`ExtraParams` that cannot be represented exactly by the helper's chosen native
@@ -79,10 +79,10 @@ and contrast with the already-preserving runtime path.
**Priority:** P2. Confirmed schema-packaging gap; remediation requires choosing
how provider-facing schemas accommodate the existing local-reference feature.
**Code:** [preparedValidation.SchemaDocument](../../../internal/validate/standard_validator.go:63),
[StandardValidator.PrepareValidation](../../../internal/validate/standard_validator.go:74),
[FSValidator.PrepareValidation](../../../internal/validate/standard_validator.go:126),
and [structuredOutputFromValidationPlan](../../../internal/usecase/runner.go:419).
**Code:** [preparedValidation.SchemaDocument](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/validate/standard_validator.go#L63),
[StandardValidator.PrepareValidation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/validate/standard_validator.go#L74),
[FSValidator.PrepareValidation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/validate/standard_validator.go#L126),
and [structuredOutputFromValidationPlan](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/d9f6aad/internal/usecase/runner.go#L419).
**Circumstances:** A JSON Schema output contract uses a root schema referring to
another file within the configured schema source. The

12
docs/roadmap/audit/02-efficiency.md
View File

@@ -42,8 +42,8 @@ guarantee, cache, caller limit, or release gate is proposed.
**Priority:** P2. Requirement-inspection path; most relevant to deeply nested
conditions rather than ordinary small templates.
**Code:** [evaluateCommand](../../../internal/prompt/requirements.go:142) and
[mergeConditionEvaluations](../../../internal/prompt/requirements.go:318).
**Code:** [evaluateCommand](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/prompt/requirements.go#L142) and
[mergeConditionEvaluations](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/prompt/requirements.go#L318).
Each comparison recursively evaluates its operands, then allocates fresh
`missingVariables` and `contentInputs` maps and copies both operands' accumulated
@@ -73,7 +73,7 @@ and partial-result behavior; interpreting more expressions is not necessary.
**Priority:** P3. Construction-time improvement with an existing depth bound.
**Code:** [overlayProviderMap](../../../internal/configuration/targets.go:131).
**Code:** [overlayProviderMap](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/configuration/targets.go#L131).
The helper deep-copies the entire lower map before considering overrides. When
both values at a key are maps, it recursively invokes itself on a descendant
@@ -106,9 +106,9 @@ validation/bounds; do not replace ConfigKit's configuration machinery.
**Priority:** P3. Scalability opportunity for engines with many namespaces.
**Code:** [filterIdentityList](../../../internal/engine/engine.go:306),
[ListPrompts](../../../internal/engine/engine.go:270), and the
[configuration inventory methods](../../../internal/configuration/listing.go:14).
**Code:** [filterIdentityList](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/engine/engine.go#L306),
[ListPrompts](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/engine/engine.go#L270), and the
[configuration inventory methods](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/0d27252/internal/configuration/listing.go#L14).
A named-namespace request first obtains a detached copy of all N identities and
then scans it to build its k matching results. Even an absent namespace costs

38
docs/roadmap/audit/03-complexity.md
View File

@@ -39,10 +39,10 @@ dependencies were changed, and no empirical testing or benchmarks were needed.
## 1. Consolidate Schema Compilation And Express The Runner's Actual Interface
**Code:** [validator interfaces](../../../internal/validate/validator.go:10),
[schema implementations](../../../internal/validate/standard_validator.go:45),
[runner preparation](../../../internal/usecase/runner.go:398), and
[engine assembly](../../../internal/engine/engine.go:133).
**Code:** [validator interfaces](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/validate/validator.go#L10),
[schema implementations](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/validate/standard_validator.go#L45),
[runner preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/usecase/runner.go#L398), and
[engine assembly](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/engine/engine.go#L133).
**Complexity:** The validator maintains direct validation and prepared
validation, with separate filesystem and `fs.FS` compilation paths. Compiler
@@ -72,10 +72,10 @@ without treating this refactor alone as its fix.
## 2. Decompose Configuration Validation And Resource Materialization
**Code:** [validateEffective](../../../internal/configuration/load.go:410),
[materializePrompt](../../../internal/configuration/prompts.go:58),
[buildExecutionProfiles](../../../internal/configuration/targets.go:14), and
[resolution callbacks](../../../internal/configuration/resolve_prompts.go:10).
**Code:** [validateEffective](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/load.go#L410),
[materializePrompt](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/prompts.go#L58),
[buildExecutionProfiles](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/targets.go#L14), and
[resolution callbacks](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/configuration/resolve_prompts.go#L10).
**Complexity:** `validateEffective` combines namespace checks, reference indexes,
backend settings, capacity arithmetic, smoke metadata, profile bounds, and prompt
@@ -105,10 +105,10 @@ Avoid a reflection-driven field schema that obscures the domain rules.
## 3. Untangle Requirement Traversal, Expression Evaluation, And Evidence
**Code:** [requirement walker](../../../internal/prompt/requirements.go:356),
[syntax dispatch](../../../internal/prompt/requirements.go:451),
[condition evaluation](../../../internal/prompt/requirements.go:93), and
[command traversal](../../../internal/prompt/requirements.go:652).
**Code:** [requirement walker](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L356),
[syntax dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L451),
[condition evaluation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L93), and
[command traversal](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/prompt/requirements.go#L652).
**Complexity:** The approximately thousand-line file contains mutually recursive
syntax walking and partial expression evaluation, branch reachability, caller
@@ -137,9 +137,9 @@ but separate; a mechanical file split would not fix it.
## 4. Clarify Ownership And Policies Across The JSON Value Walkers
**Code:** [source mapping conversion](../../../provider_values.go:31),
[bounded JSON copying](../../../internal/jsonvalue/jsonvalue.go:67), and
[public-value copying](../../../convert.go:406).
**Code:** [source mapping conversion](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/provider_values.go#L31),
[bounded JSON copying](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/jsonvalue/jsonvalue.go#L67), and
[public-value copying](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/convert.go#L406).
**Complexity:** Three recursive reflection-based paths independently handle
interfaces/pointers, maps, sequences, scalars, and nil values. Each adds its own
@@ -168,10 +168,10 @@ complexity; retain separate small adapters where their policies differ.
## 5. Extract Attempt Accounting From Generation Control Flow
**Code:** [Coordinator.generate](../../../internal/generation/coordinator.go:98),
[generateInjected](../../../internal/generation/coordinator.go:203),
[execute](../../../internal/generation/coordinator.go:303), and
[diagnostic evidence consumers](../../../internal/usecase/smoke_tester.go:246).
**Code:** [Coordinator.generate](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/generation/coordinator.go#L98),
[generateInjected](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/generation/coordinator.go#L203),
[execute](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/generation/coordinator.go#L303), and
[diagnostic evidence consumers](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5adc1c1/internal/usecase/smoke_tester.go#L246).
**Complexity:** The coordinator interleaves permit acquisition, dispatch,
cancellation, retry decisions, observer events, diagnostic evidence, and

30
docs/roadmap/audit/05-resources.md
View File

@@ -30,9 +30,9 @@ existing protected behavior; they do not cover all findings below.
**Priority:** P2. Unbounded remote-response consumption; a finite limit would be
a new policy decision, not enforcement of an existing documented byte limit.
**Code:** [runOpenRouterKey](../../../internal/usecase/smoke_authentication.go:66),
[recognizedOpenRouterKeyResponse](../../../internal/usecase/smoke_authentication.go:139),
and [diagnostic HTTP execution](../../../internal/llm/http_evidence.go:129).
**Code:** [runOpenRouterKey](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/smoke_authentication.go#L66),
[recognizedOpenRouterKeyResponse](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/smoke_authentication.go#L139),
and [diagnostic HTTP execution](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/llm/http_evidence.go#L129).
**Circumstances:** An authentication endpoint returns HTTP 200 with a large or
continuously growing body. Recognition calls unrestricted `io.ReadAll` and then
@@ -63,10 +63,10 @@ artifacts, or generated output.
**Priority:** P2. Potentially exponential allocation before upstream resource
checks can run.
**Code:** [providerMapForMapping](../../../provider_values.go:19),
[providerValueForMapping](../../../provider_values.go:31),
[ProfileSource](../../../profiles.go:33), and
[BackendSource](../../../backends.go:100).
**Code:** [providerMapForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/provider_values.go#L19),
[providerValueForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/provider_values.go#L31),
[ProfileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/profiles.go#L33), and
[BackendSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/backends.go#L100).
**Circumstances:** A caller builds a small acyclic Go value graph containing
repeated map/slice references. Each level can point twice to the same child:
@@ -107,10 +107,10 @@ configuration limits to fix this pre-handoff allocation problem.
**Priority:** P3. Avoidable retained-memory dependency after use/discard.
**Code:** [PreparedExecution.owner](../../../internal/usecase/prepared_execution.go:24),
[Discard](../../../internal/usecase/prepared_execution.go:96),
[claim](../../../internal/usecase/prepared_execution.go:172), and
[payload clearing](../../../internal/usecase/prepared_execution.go:188).
**Code:** [PreparedExecution.owner](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L24),
[Discard](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L96),
[claim](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L172), and
[payload clearing](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/prepared_execution.go#L188).
**Circumstances:** A consumer retains a completed or discarded handle for its
supported `Details` access, while replacing or dropping the originating engine.
@@ -141,7 +141,7 @@ collaborators is implied.
**Priority:** P3. Avoidable memory amplification on validation failures.
**Code:** [formatRepairDiagnostics](../../../internal/usecase/repairer.go:119).
**Code:** [formatRepairDiagnostics](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/repairer.go#L119).
**Circumstances:** A failed schema validation produces a large diagnostic or many
diagnostics and repair is enabled. The formatter normalizes every string, marshals
@@ -170,9 +170,9 @@ implementation opportunity, not a claim that the existing contract promises a
**Priority:** P3. Avoidable backing-buffer retention in retained metadata.
**Code:** [NormalizeSessionID](../../../internal/domain/session.go:10),
[preparation](../../../internal/usecase/runner.go:312), and
[prepared metadata construction](../../../internal/usecase/runner.go:491).
**Code:** [NormalizeSessionID](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/domain/session.go#L10),
[preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/runner.go#L312), and
[prepared metadata construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/fb87fab/internal/usecase/runner.go#L491).
**Circumstances:** A direct or rendered session ID contains substantial leading
or trailing whitespace around a short valid identifier. `strings.TrimSpace`

20
docs/roadmap/audit/06-error-handling.md
View File

@@ -44,9 +44,9 @@ not repeated here.
**Priority:** P2. Confirmed public error-classification defect.
**Code:** [publicErrorFor](../../../errors.go:63),
[mapPublicError](../../../errors.go:16), and
[wrapGenerationError](../../../internal/usecase/runner.go:271).
**Code:** [publicErrorFor](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/errors.go#L63),
[mapPublicError](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/errors.go#L16), and
[wrapGenerationError](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/usecase/runner.go#L271).
**Failure condition:** An injected `LLMClient` or `ArtifactReader` returns an
error obtained from another PromptKit operation. Ordinary mapped errors retain
@@ -56,7 +56,7 @@ regardless of which operation the outer runner classified.
**Expected:** A model-client failure matches `ErrLLMGenerate`; an artifact-reader
failure matches `ErrArtifactLoad`. The injected cause remains available through
`errors.Is`, as their [public GoDoc](../../../engine.go:49) specifies. Preserving
`errors.Is`, as their [public GoDoc](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/engine.go#L49) specifies. Preserving
the nested cause may also preserve its public categories; it must not replace
the category for the operation that just failed.
@@ -89,7 +89,7 @@ and context identities.
**Priority:** P2. Confirmed loss of failure provenance and cause.
**Code:** [decodeOpenAIChatResponse](../../../internal/llm/openai_compatible_client.go:373).
**Code:** [decodeOpenAIChatResponse](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/llm/openai_compatible_client.go#L373).
**Failure condition:** A 2xx response body returns a non-EOF I/O error other than
`context.Canceled` or `context.DeadlineExceeded`, either during the first decode
@@ -99,7 +99,7 @@ while reading the response stream after headers were received.
**Expected:** Distinguish an underlying read/transport failure from evidence of
invalid JSON or trailing data. Retain the read cause through a redacting error
so callers can inspect it with `errors.Is`/`errors.As`, consistent with the
[transport category](../../../engine.go:65). Do not report trailing data when the
[transport category](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/engine.go#L65). Do not report trailing data when the
reader failed without supplying any. This does not change the established
classification of invalid/truncated JSON or introduce transport retries.
@@ -133,9 +133,9 @@ private transport details.
**Priority:** P2. Confirmed mismatch with the diagnostic error contract.
**Code:** [runInference](../../../internal/usecase/smoke_tester.go:207),
[generation preparation](../../../internal/generation/coordinator.go:96), and
[request payload validation](../../../internal/llm/openai_compatible_client.go:511).
**Code:** [runInference](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/usecase/smoke_tester.go#L207),
[generation preparation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/generation/coordinator.go#L96), and
[request payload validation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/internal/llm/openai_compatible_client.go#L511).
**Failure condition:** An inference diagnostic's effective settings are invalid
in a way detected by built-in request construction rather than target selection.
@@ -144,7 +144,7 @@ is one public example. The coordinator returns `llm.ErrInvalidRequest` before
dispatch with no attempt evidence. `runInference` treats every generation error
as a concluded diagnostic failure.
**Expected:** The [SmokeTest contract](../../../smoke_diagnostics.go:238) says invalid
**Expected:** The [SmokeTest contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/6b1323d/smoke_diagnostics.go#L238) says invalid
kinds, settings, and selections return an ordinary Go error before diagnostic
work. A locally invalid request should follow that path and expose the public
invalid-request category. This is distinct from a provider rejecting a validly

14
docs/roadmap/audit/07-security.md
View File

@@ -62,10 +62,10 @@ operations described below rather than inferred from interface-call traces.
**Priority:** P2. Build/deployment security finding, not a newly discovered
PromptKit algorithm defect.
**Relevant code:** [declared Go minimum](../../../go.mod:3),
[default HTTP-client construction](../../../internal/llm/openai_compatible_client.go:58),
[generation dispatch](../../../internal/llm/openai_compatible_client.go:211), and
[diagnostic dispatch](../../../internal/llm/http_evidence.go:129).
**Relevant code:** [declared Go minimum](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/go.mod#L3),
[default HTTP-client construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/openai_compatible_client.go#L58),
[generation dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/openai_compatible_client.go#L211), and
[diagnostic dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/http_evidence.go#L129).
**Condition and impact:** The local toolchain used for this audit is Go 1.27.0.
Applications built with that patch can exercise affected standard-library
@@ -111,9 +111,9 @@ HTTP/2 ban, or a new recurring release gate.
response boundary. This is the same mechanism as resource-management audit
finding 1, not a second independent remediation item.
**Relevant code:** [authentication recognition](../../../internal/usecase/smoke_authentication.go:139),
[authentication probe execution](../../../internal/usecase/smoke_authentication.go:66),
and [diagnostic HTTP execution](../../../internal/llm/http_evidence.go:129).
**Relevant code:** [authentication recognition](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/usecase/smoke_authentication.go#L139),
[authentication probe execution](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/usecase/smoke_authentication.go#L66),
and [diagnostic HTTP execution](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/cf0bfd4/internal/llm/http_evidence.go#L129).
**Condition:** A consumer explicitly invokes an `openrouter_key` authentication
diagnostic. The selected endpoint, a compromised provider, or an intermediary

48
docs/roadmap/audit/08-testing.md
View File

@@ -62,8 +62,8 @@ rather than becoming duplicate remediation projects.
**Priority:** P2. Missing protection for a documented confidentiality boundary.
**Relevant code:** [RunRequest formatting](../../../formatting.go:5) and the
analogous existing [SmokeTestRequest privacy test](../../../smoke_test_contract_test.go:135).
**Relevant code:** [RunRequest formatting](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/formatting.go#L5) and the
analogous existing [SmokeTestRequest privacy test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/smoke_test_contract_test.go#L135).
**Deficiency:** `RunRequest.String`, `GoString`, and their shared formatter all
have 0% combined statement coverage. The suite protects formatting of generated
@@ -86,12 +86,12 @@ Reflection-based disclosure is explicitly outside this formatter guarantee.
**Priority:** P2. An exported source-selection path is entirely unprotected.
**Relevant code:** [WithSchemaFile](../../../engine.go:212),
[SetSchemaFile](../../../internal/engine/engine.go:75), and
[fileSource](../../../internal/engine/engine.go:211).
**Relevant code:** [WithSchemaFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/engine.go#L212),
[SetSchemaFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/engine/engine.go#L75), and
[fileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/engine/engine.go#L211).
**Deficiency:** All three functions have 0% combined coverage. The existing
[single-file validator test](../../../internal/validate/standard_validator_test.go:596)
[single-file validator test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/validate/standard_validator_test.go#L596)
constructs `FSValidator` directly with `fstest.MapFS`; it does not test the public
option, host-file selection, or its engine wiring.
@@ -113,9 +113,9 @@ helper-by-helper test matrix or model-provider access.
**Priority:** P2. Conversion and ownership coverage misses known data-integrity
and deferred-error risks.
**Relevant tests:** [programmatic source ownership/order](../../../sources_contract_test.go:14)
and [programmatic construction](../../../construction_contract_test.go:226).
**Implementation:** [providerValueForMapping](../../../provider_values.go:31).
**Relevant tests:** [programmatic source ownership/order](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/sources_contract_test.go#L14)
and [programmatic construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/construction_contract_test.go#L226).
**Implementation:** [providerValueForMapping](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/provider_values.go#L31).
**Deficiency:** The converter has only 11.9% combined coverage. The principal
source-ownership test mutates a flat string-valued map. It does not establish
@@ -143,10 +143,10 @@ coverage for the separately identified shared-graph issue belongs with that fix.
**Priority:** P2. Covered code paths lack important boundary-case assertions.
**Relevant tests:** [public generation failures](../../../generation_error_contract_test.go:111),
[direct mapper cases](../../../errors_internal_test.go:13),
[body cancellation](../../../internal/llm/prepared_generation_test.go:161), and
[inference diagnostic cases](../../../internal/usecase/smoke_inference_test.go:14).
**Relevant tests:** [public generation failures](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/generation_error_contract_test.go#L111),
[direct mapper cases](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/errors_internal_test.go#L13),
[body cancellation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/llm/prepared_generation_test.go#L161), and
[inference diagnostic cases](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/usecase/smoke_inference_test.go#L14).
**Deficiency and demonstrated blind spots:**
@@ -180,9 +180,9 @@ precedence, best-effort non-2xx detail parsing, and status-only retry policy.
**Priority:** P2. Missing assembled validation-to-wire assertion.
**Relevant tests:** [prepared execution source freezing](../../../prepared_execution_contract_test.go:19),
its [referenced schema fixture](../../../prepared_execution_contract_test.go:809),
and [local reference validation](../../../internal/validate/standard_validator_test.go:627).
**Relevant tests:** [prepared execution source freezing](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/prepared_execution_contract_test.go#L19),
its [referenced schema fixture](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/prepared_execution_contract_test.go#L809),
and [local reference validation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/validate/standard_validator_test.go#L627).
**Deficiency:** Local tests establish that referenced schemas compile and
validate. The prepared-execution test checks that the injected client's schema
@@ -210,11 +210,11 @@ promise support for arbitrary provider schema dialect features.
**Priority:** P3. Remove or rewrite change-detector assertions, retaining the
substantive file-reading tests.
**Relevant assertions:** [size-hint test](../../../internal/artifact/reader_test.go:287)
and [benchmark correctness check](../../../internal/artifact/reader_benchmark_test.go:156).
**Relevant assertions:** [size-hint test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/artifact/reader_test.go#L287)
and [benchmark correctness check](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/artifact/reader_benchmark_test.go#L156).
**Deficiency:** Both independently calculate a hex SHA-256 digest and require
that exact value. The [public Artifact.Hash contract](../../../types.go:290)
that exact value. The [public Artifact.Hash contract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/types.go#L290)
expressly leaves its format and algorithm unspecified. A legitimate algorithm
or encoding change would fail tests unrelated to the requested behavior.
@@ -222,7 +222,7 @@ or encoding change would fail tests unrelated to the requested behavior.
opaque equality relationships needed for each test. For the under/overreported
size cases, comparing with the inline reader for the same complete body still
detects hashing only a reported-size prefix. The existing
[source-parity test](../../../internal/artifact/reader_test.go:27) already owns
[source-parity test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/artifact/reader_test.go#L27) already owns
repeatability, same-content equality, and changed-content inequality. Retain
body, actual-size, metadata, and read-boundary assertions. The benchmark may
reuse an opaque expected hash prepared outside measurement or rely on the
@@ -232,10 +232,10 @@ owning behavioral test; it need not maintain its own SHA-256 contract.
**Priority:** P3. Consolidation/removal candidate for duplicated assertions.
**Relevant tests:** [internal complete catalog table](../../../internal/configuration/bundled_test.go:12),
[public option/inventory table](../../../bundled_openrouter_contract_test.go:54),
[HTTP payload matrix](../../../bundled_execution_contract_test.go:51), and
[bundled smoke defaults](../../../bundled_smoke_contract_test.go:16).
**Relevant tests:** [internal complete catalog table](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/internal/configuration/bundled_test.go#L12),
[public option/inventory table](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/bundled_openrouter_contract_test.go#L54),
[HTTP payload matrix](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/bundled_execution_contract_test.go#L51), and
[bundled smoke defaults](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/f7085d7/bundled_smoke_contract_test.go#L16).
**Deficiency:** The current count of 17, complete ID inventory, selected
ID-to-model mappings, tier-plugin data, and diagnostic default model recur

28
docs/roadmap/audit/09-interfaces.md
View File

@@ -33,9 +33,9 @@ to change those behaviors.
**Priority:** P2. A documented ownership permission permits data races and
inconsistent input snapshots.
**Relevant interfaces/code:** [ArtifactReader GoDoc](../../../types.go:294),
[public reader adapter](../../../artifact_reader.go:19), and
[copyBytes](../../../convert.go:490).
**Relevant interfaces/code:** [ArtifactReader GoDoc](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/types.go#L294),
[public reader adapter](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/artifact_reader.go#L19), and
[copyBytes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/convert.go#L490).
**Contract defect:** The interface says that `Read` may be called concurrently
and that the reader may reuse or mutate the returned artifact and body after
@@ -72,11 +72,11 @@ the selected lifetime, without globally serializing unrelated engine work.
**Priority:** P2. The public inspection contract describes valid results as
impossible and incorrectly limits the sources that can satisfy a requirement.
**Relevant interfaces/code:** [Engine.InspectProfile](../../../engine.go:313),
[ProfileInspection.APIKeyRequired](../../../types.go:372),
**Relevant interfaces/code:** [Engine.InspectProfile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/engine.go#L313),
[ProfileInspection.APIKeyRequired](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/types.go#L372),
[profile-inspection consumer example](../../consumers/pkg-promptkit.md#inspect-a-profile-before-prompt-work),
[effective-target construction](../../../internal/configuration/targets.go:99),
and [credential availability check](../../../internal/usecase/runner.go:611).
[effective-target construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets.go#L99),
and [credential availability check](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/usecase/runner.go#L611).
**Contract defect:** Both method and field GoDoc claim that `APIKeyRequired`
is mutually exclusive with a nonblank `EffectiveModelParams.APIKeyEnv`. They
@@ -97,7 +97,7 @@ reject this valid combination or report credential readiness incorrectly.
**Evidence:** A temporary public-API diagnostic demonstrated that combination
and successful preparation. The existing
[effective-target test](../../../internal/configuration/targets_test.go:88)
[effective-target test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets_test.go#L88)
also includes a required profile with an explicit environment source.
**Potential remediation:** Describe the flag as a local credential-availability
@@ -114,8 +114,8 @@ provider parameters.
**Relevant interfaces/code:** [integration request-body contract](../../integrations/openai-compatible-chat.md#request-body),
[profile defaulting reference](../../formats.md#defaults-and-overrides),
[overlayProviderMap](../../../internal/configuration/targets.go:133), and
[runtime override merge](../../../internal/usecase/runner.go:562).
[overlayProviderMap](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets.go#L133), and
[runtime override merge](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/usecase/runner.go#L562).
**Contract defect:** The integration document says backend, profile, and request
extra-parameter maps all use whole-map replacement. Actual configured profile
@@ -135,7 +135,7 @@ only `request_only: true` does remove the configured entries.
**Evidence:** A temporary public-API diagnostic observed both forms through an
injected client and confirmed the configured merged fields through a controlled
built-in HTTP transport. No external request was made. The existing
[effective-target test](../../../internal/configuration/targets_test.go:70)
[effective-target test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/internal/configuration/targets_test.go#L70)
also exercises recursive configured overlay.
**Potential remediation:** Replace the stale configuration-precedence claim
@@ -148,9 +148,9 @@ do not add another merge policy or duplicate its full configuration reference.
**Priority:** P3. Small but concrete public-contract inconsistencies.
**Relevant interfaces/code:** [ProfileInspection.ProfileID](../../../types.go:364),
[ListPrompts GoDoc](../../../listing.go:90), and
[literal profile identity test](../../../profile_inspection_contract_test.go:13).
**Relevant interfaces/code:** [ProfileInspection.ProfileID](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/types.go#L364),
[ListPrompts GoDoc](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/listing.go#L90), and
[literal profile identity test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/31f1e6a/profile_inspection_contract_test.go#L13).
**Contract defect:** `ProfileInspection.ProfileID` is described as trimmed,
but configured IDs and lookups preserve meaningful whitespace exactly.

38
docs/roadmap/audit/10-equivalence.md
View File

@@ -32,19 +32,19 @@ equivalence promise, is the preservation target.
### Evidence
- [TestJSONSchemaNumericConstraintsRetainJSONPrecision](../../../internal/validate/standard_validator_test.go:721)
- [TestJSONSchemaNumericConstraintsRetainJSONPrecision](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L721)
runs the same exact-number constraints through operating-system and `fs.FS`
validators using `jsonSchemaValidatorSources`. Both must distinguish adjacent
large integers, preserve precise decimal boundaries, and accept the same
valid instances.
- [TestJSONSchemaDecodingRequiresOneCompleteDocument](../../../internal/validate/standard_validator_test.go:805)
- [TestJSONSchemaDecodingRequiresOneCompleteDocument](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L805)
uses that same source matrix to require equivalent schema/instance framing
and the distinction between operational schema errors and rejected output.
- [TestSchemaReferencesPreserveEscapedFilenames](../../../internal/validate/standard_validator_test.go:492)
- [TestSchemaReferencesPreserveEscapedFilenames](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L492)
applies the same reference cases to both source implementations, with an
explicit platform exception for filenames illegal on Windows.
- [TestStandardValidatorPreparedSchemaSurvivesSourceRemoval](../../../internal/validate/standard_validator_test.go:228)
and [TestFSValidatorPreparedSchemaSurvivesSourceMutation](../../../internal/validate/standard_validator_test.go:416)
- [TestStandardValidatorPreparedSchemaSurvivesSourceRemoval](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L228)
and [TestFSValidatorPreparedSchemaSurvivesSourceMutation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator_test.go#L416)
separately require the same captured schema to accept an integer-valued
object and reject a string-valued one after its source changes. Their source
operations differ, but the prepared validation responsibility matches.
@@ -54,7 +54,7 @@ not require identical filesystem representations or diagnostic strings.
### Implementation
[StandardValidator and FSValidator](../../../internal/validate/standard_validator.go:74)
[StandardValidator and FSValidator](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/validate/standard_validator.go#L74)
each implement `PrepareValidation` and direct `validateJSONSchema`. The four
paths repeat compiler setup, root-resource handling, cancellation boundaries,
compilation/error wrapping, and construction or use of executable schema
@@ -97,17 +97,17 @@ correctness finding, not solved by this extraction.
### Evidence
- [TestPublicLLMClientAdapterGivesClientOwnedNestedValues](../../../llm_adapter_internal_test.go:14)
- [TestPublicLLMClientAdapterGivesClientOwnedNestedValues](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/llm_adapter_internal_test.go#L14)
requires nested provider maps, schema values, messages, and cache metadata to
remain independent when an injected client mutates and retains its request.
- [TestRunnerPreparedExecutionDetachesTransferredSnapshotSources](../../../internal/usecase/prepared_execution_test.go:634)
- [TestRunnerPreparedExecutionDetachesTransferredSnapshotSources](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/usecase/prepared_execution_test.go#L634)
separately requires nested provider maps and schema values to survive source
mutation, repeated `Details` calls, and execution without aliasing.
- [TestCopyHandlesIndirectionAndIsolatesNestedMutations](../../../internal/jsonvalue/jsonvalue_test.go:156)
- [TestCopyHandlesIndirectionAndIsolatesNestedMutations](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/jsonvalue/jsonvalue_test.go#L156)
exercises the underlying JSON-value ownership responsibility with typed
collections and repeated acyclic children. The adjacent scalar/collection
tests protect compatible concrete types and exact `json.Number` values.
- [TestCopyAndCopyMapApplyDistinctEmptyKeyRules](../../../internal/jsonvalue/jsonvalue_test.go:204)
- [TestCopyAndCopyMapApplyDistinctEmptyKeyRules](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/jsonvalue/jsonvalue_test.go#L204)
explicitly demonstrates a necessary policy distinction: general schema
objects can have empty keys, while provider maps cannot.
@@ -117,16 +117,16 @@ normalization, and copying on arbitrary Go values.
### Implementation
The facade's [copyAny/copyReflectValue](../../../convert.go:406) implements a
The facade's [copyAny/copyReflectValue](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/convert.go#L406) implements a
separate recursive reflection copier for values projected into client requests,
prepared details, results, and profile inspections. Internal prepared-state
cloning uses [clonePreparedRun](../../../internal/usecase/prepared_execution.go:226)
and [jsonvalue.Copy/CopyMap](../../../internal/jsonvalue/jsonvalue.go:30).
cloning uses [clonePreparedRun](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/usecase/prepared_execution.go#L226)
and [jsonvalue.Copy/CopyMap](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/jsonvalue/jsonvalue.go#L30).
The latter package already owns compatible JSON-tree copying and validation.
Ordinary runtime provider values reach facade projection after JSON-value
validation/copying. The runner also copies its schema document through
[structuredOutputFromValidationPlan](../../../internal/usecase/runner.go:419)
[structuredOutputFromValidationPlan](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/usecase/runner.go#L419)
before projecting it. Thus these normal runtime paths have a common accepted
value domain, even though their entry-point policies are different.
@@ -172,19 +172,19 @@ replacing them with one “all copy functions are equivalent” test.
### Evidence
- [TestAnalyzeRequirementsClassifiesKnownConditions](../../../internal/prompt/requirements_test.go:268)
- [TestAnalyzeRequirementsClassifiesKnownConditions](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L268)
verifies required/optional classification for selected and skipped `if`
branches, and directly compares the recognized branch choice with the real
Go renderer. This anchors recognized condition semantics in actual rendering.
- [TestAnalyzeRequirementsHandlesWithDotAndNestedReachability](../../../internal/prompt/requirements_test.go:332)
- [TestAnalyzeRequirementsHandlesWithDotAndNestedReachability](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L332)
requires the same selected/skipped classification for `with` and nested
`if`, while separately protecting `with`'s changed dot and preserved root
caller-map access.
- [TestAnalyzeRequirementsReportsUnresolvedDecisionAndContentConditions](../../../internal/prompt/requirements_test.go:369)
- [TestAnalyzeRequirementsReportsUnresolvedDecisionAndContentConditions](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L369)
protects conditional dependencies and meaningful incompleteness for unknown
decisions. It also establishes that an unresolved condition around plain
text alone does not make discovery incomplete.
- [TestAnalyzeRequirementsDoesNotHideCallerMapScopes](../../../internal/prompt/requirements_test.go:14)
- [TestAnalyzeRequirementsDoesNotHideCallerMapScopes](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements_test.go#L14)
compares several scope forms against actual template execution while allowing
incomplete analysis for constructs outside recognition scope.
@@ -195,7 +195,7 @@ or completely interpret arbitrary templates.
### Implementation
The `IfNode` and `WithNode` cases in
[requirementWalker.visit](../../../internal/prompt/requirements.go:451)
[requirementWalker.visit](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/5177db0/internal/prompt/requirements.go#L451)
independently perform inactive-path traversal, condition evaluation, then/else
reachability selection, dependency-counter comparison, and limitation recording.
`with` adds a different body-dot calculation. `branchReach`, condition

28
docs/roadmap/audit/11-boundaries.md
View File

@@ -33,10 +33,10 @@ release blockers.
## 1. Retire The Test-Only Capacity Client As A Production Scheduling Surface
**Relevant code:** [capacity.NewClient and client.Generate](../../../internal/capacity/client.go:17),
[generation constructors and dispatch](../../../internal/generation/coordinator.go:37),
[engine assembly](../../../internal/engine/engine.go:157), and
[runner scheduling test](../../../internal/usecase/runner_test.go:2391).
**Relevant code:** [capacity.NewClient and client.Generate](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/capacity/client.go#L17),
[generation constructors and dispatch](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/generation/coordinator.go#L37),
[engine assembly](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/engine/engine.go#L157), and
[runner scheduling test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/runner_test.go#L2391).
**Basis:** The engine selects `generation.NewBuiltIn` or `NewInjected` for every
production engine. The coordinator owns active-permit acquisition around each
@@ -77,10 +77,10 @@ identified; current test reachability alone does not establish one.
## 2. Put OpenRouter Authentication Protocol Details Behind The Outbound Adapter
**Relevant code:** [authenticationProbe.runOpenRouterKey](../../../internal/usecase/smoke_authentication.go:66),
[recognizedOpenRouterKeyResponse](../../../internal/usecase/smoke_authentication.go:139),
[diagnostic endpoint derivation](../../../internal/usecase/smoke_selection.go:166),
and [HTTP authentication transport](../../../internal/llm/http_evidence.go:111).
**Relevant code:** [authenticationProbe.runOpenRouterKey](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_authentication.go#L66),
[recognizedOpenRouterKeyResponse](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_authentication.go#L139),
[diagnostic endpoint derivation](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_selection.go#L166),
and [HTTP authentication transport](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/llm/http_evidence.go#L111).
**Basis:** `internal/usecase` currently interprets OpenRouter-specific HTTP
statuses and the account-response keys `data`, `label`, `is_free_tier`, and
@@ -97,7 +97,7 @@ knowledge. The [architecture policy](../../policy/architecture.md#architectural-
calls for encapsulating external integration details in internal adapters.
The parser is already functionally isolated, making the ownership seam fairly
small. The authentication tests in
[smoke_authentication_test.go](../../../internal/usecase/smoke_authentication_test.go:64)
[smoke_authentication_test.go](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_authentication_test.go#L64)
also show that this is provider protocol behavior rather than application
selection policy.
@@ -134,10 +134,10 @@ read is a separate resource/security finding; relocation alone does not fix it.
## 3. Narrow Smoke-Value Copy Helpers To Their Actual Ownership Boundaries
**Relevant code:** [domain.CloneSmokeTestRequest](../../../internal/domain/smoke_diagnostics.go:157),
[domain.CloneSmokeTestReport](../../../internal/domain/smoke_diagnostics.go:179),
[smokeReportTarget](../../../internal/usecase/smoke_tester.go:432), and
[public smoke-value conversion](../../../smoke_diagnostics.go:279).
**Relevant code:** [domain.CloneSmokeTestRequest](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/domain/smoke_diagnostics.go#L157),
[domain.CloneSmokeTestReport](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/domain/smoke_diagnostics.go#L179),
[smokeReportTarget](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/internal/usecase/smoke_tester.go#L432), and
[public smoke-value conversion](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/smoke_diagnostics.go#L279).
**Basis:** `CloneSmokeTestRequest` is called only by its own domain test;
actual request ownership is established by public-to-domain conversion.
@@ -172,7 +172,7 @@ ownership behavior.
Preserve provider-map error propagation, caller-owned result values, and
credential/endpoint redaction. Keep the meaningful
[public conversion ownership test](../../../smoke_conversion_internal_test.go:13)
[public conversion ownership test](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/b39460a/smoke_conversion_internal_test.go#L13)
and relevant use-case report tests. If genuine internal whole-report snapshots
are needed, retaining an explicitly used domain cloner is a reasonable
alternative. This finding does not require sharing public/internal DTO types

36
docs/roadmap/audit/12-deadcode.md
View File

@@ -27,15 +27,15 @@ for deleting a supported public feature or imposing a new release gate.
## 1. Remove Backend Presence Bookkeeping With No Runtime Consumer
**Relevant code:** [loaded.backends](../../../internal/configuration/load.go:122),
[backendFields and presence capture](../../../internal/configuration/load.go:215),
[effective backend construction](../../../internal/configuration/targets.go:14),
and [Backend.QueueCapacitySet](../../../internal/domain/domain.go:187).
**Relevant code:** [loaded.backends](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load.go#L122),
[backendFields and presence capture](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load.go#L215),
[effective backend construction](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/targets.go#L14),
and [Backend.QueueCapacitySet](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L187).
**Evidence:** Construction allocates a per-backend field-state map and fills it
through `captureFields(..., state.backends)`. No production code reads the
recorded backend states. The only lookup of the captured queue state is in
[TestLoadDefaultsAbsentQueueCapacity](../../../internal/configuration/load_test.go:755).
[TestLoadDefaultsAbsentQueueCapacity](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/load_test.go#L755).
Unlike profile presence, backend presence is not consumed while constructing
effective execution targets.
@@ -46,7 +46,7 @@ explicit queue setting from a derived default. The registry's capacity-policy
projection uses `ConcurrencyLimit` and `QueueCapacity`, not this flag.
**Why obsolete:** Queue defaulting and its provenance are already handled by
[resolveBackends](../../../internal/configuration/resolve_targets.go:11) and
[resolveBackends](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/resolve_targets.go#L11) and
ConfigKit's derived-default record. Typed final values drive runtime capacity;
the retained side map and Boolean do not contribute to that behavior or to the
public inspection view. No documented compatibility or planned-feature need for
@@ -66,11 +66,11 @@ under the [configuration-boundary ADR](../../adr/0001-configuration-boundary.md)
## 2. Retire Legacy Fields In The Captured Prompt Representation
**Relevant code:** [PromptDefinition.OutputFormat](../../../internal/domain/domain.go:148),
[PromptMessageTemplate.ContentFile](../../../internal/domain/domain.go:173),
[prompt materialization](../../../internal/configuration/prompts.go:58),
[resolveOutputContract](../../../internal/usecase/runner.go:639), and
[definition hashing](../../../internal/promptdef/hash.go:12).
**Relevant code:** [PromptDefinition.OutputFormat](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L148),
[PromptMessageTemplate.ContentFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/domain.go#L173),
[prompt materialization](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/configuration/prompts.go#L58),
[resolveOutputContract](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/runner.go#L639), and
[definition hashing](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/promptdef/hash.go#L12).
**Evidence:** Supported engine construction requires and validates a complete
output contract. Materialization sets `definition.Validation` to that contract
@@ -113,10 +113,10 @@ representation, not part of the public stable DTO shapes.
## 3. Remove Unused Diagnostic State And A Discarded Helper Result
**Relevant code:** [reachabilityProbeOutcome.initialEndpoint](../../../internal/usecase/smoke_reachability.go:24),
[HTTP report assembly](../../../internal/usecase/smoke_tester.go:376),
[fileSource](../../../internal/engine/engine.go:211), and
[SetSchemaFile](../../../internal/engine/engine.go:75).
**Relevant code:** [reachabilityProbeOutcome.initialEndpoint](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/smoke_reachability.go#L24),
[HTTP report assembly](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/smoke_tester.go#L376),
[fileSource](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/engine/engine.go#L211), and
[SetSchemaFile](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/engine/engine.go#L75).
**Evidence:** The reachability probe assigns its private outcome's
`initialEndpoint`, but the smoke tester never reads that member. It records
@@ -144,15 +144,15 @@ though an extra private field/result is unnecessary.
**Relevant code and evidence:**
- [filecatalog.RelativePath](../../../internal/filecatalog/catalog.go:71) is
- [filecatalog.RelativePath](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/filecatalog/catalog.go#L71) is
called only by `TestRelativePathNested`. Current source discovery and
source-relative resource resolution use other helpers; no production or
public-facade caller uses this wrapper around `filepath.Rel`.
- [resourceNamespaceFromID](../../../internal/domain/resource_identity.go:34)
- [resourceNamespaceFromID](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/domain/resource_identity.go#L34)
is called only by `TestResourceNamespaceFromID`. Actual namespace inventory
and filtering paths do not call it. The exported identity-validation and
qualification operations remain active and are not candidates for removal.
- [runner_test.go:stringPtr](../../../internal/usecase/runner_test.go:2592)
- [runner_test.go:stringPtr](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/3b76031/internal/usecase/runner_test.go#L2592)
has no callers, including in tests. Both reachability analysis and
Staticcheck `U1000` report it.

10
docs/roadmap/implementation.md
View File

@@ -469,6 +469,16 @@ names/claims to separate historical audit evidence from stale current guidance.
## Stage 17: Validate And Close The Sprint
**Completed:** Findings 1–7 are implemented and finding 8's runtime behavior is
preserved. With Go 1.27.3, `go test -race ./...` and `go vet ./...` passed,
including maintained examples. All tracked Go files are formatted; full diff
whitespace and repository hygiene checks passed. A local Markdown destination
and heading scan checked 580 links in 63 files; 153 historical code references
were corrected to their audit commits and verified against those Git objects.
Remaining validating copies are confined to acceptance/overlay boundaries;
trusted copies and transfers retain the documented ownership boundaries. No
release, push, or publication was performed.
**Scope:** combined final state, all findings and deferred checks.
1. Resolve remaining deferred compilation/tests; format changed Go files. Run

10
docs/roadmap/responsibility-simplification.md
View File

@@ -9,8 +9,7 @@ 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.
The selected implementation is delivered; final combined validation and
repository hygiene checks remain pending.
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;
@@ -48,8 +47,8 @@ throughput, complexity, or numerical-precision guarantees.
## Selected Work
The following sections record the accepted work and its rationale. The target
above is implemented; final combined checks are tracked in the implementation
plan rather than inferred from the audit's baseline tests.
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
@@ -222,7 +221,8 @@ 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.
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.