cache-control pointers, effective extra parameters, and structured-output
schemas. Internal credential and target-presence fields do not escape.
- **Inspection and extension conversion:** Profile and prompt inspection
outputs are independent copies. Generation requests receive copied prompt,
target, presence, and structured-output values; generation responses contain
no mutable fields requiring additional copying.
- **Copy-rule ownership:** Caller-supplied JSON-compatible values enter through
`internal/jsonvalue` validation and copying. The outward conversion helpers
copy already-validated domain snapshots without introducing a second
acceptance policy. No consolidation finding was warranted in this scope.
- **Public errors:** Not-found identities remain distinct from load failures;
profile-required and missing-credential errors retain their more specific
identity together with `ErrInvalidRequest`; collaborator and cancellation
identities remain discoverable; and typed capacity errors expose only a
copied backend ID plus `ErrCapacityExceeded` rather than the internal error
type. Nil and zero `CapacityError` values are safe.
- **Diagnostic formatting:** `RunRequest` and `GenerateRequest` currently omit
direct credentials and content from `String`, `GoString`, `%+v`, and `%#v`.
`PreparedExecution` always formats as an opaque constant, including through
a copied handle. Prepared and result values intentionally expose rendered or
generated content as documented in package GoDoc; applications retain
responsibility for logging those content-bearing values.
- **Prepared handle values:** Nil and zero handles return zero details and may
be discarded safely. Details are fresh deep copies and remain stable after
execution or discard. Copying a handle shares its single-use lifecycle
without exposing the internal representation.
- **Test ownership:** Root external-package tests appropriately own public
snapshots, structured error identity, and opaque-handle behavior. Focused
internal error-mapping tests cover internal-type containment. The one
material redaction gap is recorded as S01-F01.
### Verification Performed
The code knowledge graph was used to discover the scoped symbols, trace their
callers and callees through the facade and internal domain boundary, and locate
the focused tests. Important conclusions were confirmed against source.
The following focused commands passed:
```sh
go test . -run 'Test(PreparedRunJSONDoesNotExposeSecretOrTargetPresence|RunRequestFormattingRedactsDirectAPIKey|GenerateRequestFormattingRedactsDirectAPIKey|MapPublicErrorPreservesGenerationCancellation|MapPublicErrorTranslatesCapacityError|CapacityExceededSentinelContract|InspectProfileReturnsIndependentTargetMatchingPreparation|InspectPromptReturnsIndependentMetadataMatchingPreparation|PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|PreparedExecutionLifecycleAndEngineBinding|PreparedExecutionDiscardAndFormattingDoNotExposePrivateState|InMemoryProfileExtraParamsAreCopiedAcrossPublicBoundary|ExtraParamsTypedNestedValuesAreCopiedAcrossPublicBoundary|ArtifactReaderReceivesPublicReferenceAndPreparesArtifact|RunPassesPreparedRequestToInjectedLLMClient|PublicErrorsSupportErrorsIs)$'
go test -race . -run 'Test(PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|PreparedExecutionConcurrentClaimAllowsOneGeneration|PreparedExecutionRunAndDiscardRaceHasOneWinner|PreparedExecutionDiscardAndFormattingDoNotExposePrivateState|MapPublicErrorTranslatesCapacityError|RunRequestFormattingRedactsDirectAPIKey|GenerateRequestFormattingRedactsDirectAPIKey)$' -count=3
```
### Handoff
- Execute the missing Stage 0 baseline before relying on this file as a
complete audit ledger or beginning the next component review.
- Stage 2 owns public configuration helpers, `json.go`, extension-adapter
implementation, and adapter-specific mutation and cancellation behavior.
- Stages 3 and 4 own engine construction and runtime operations respectively;
this review did not evaluate those paths beyond tracing their use of the
session, artifact, and backend-identity behavior is partly protected. The
confirmed overflow is S02-F01 and manual mapping drift is S02-F05.
- **Filesystem, reader, and client ownership:** Reader and client values are
stored as narrow injected interfaces and mutable values crossing their
adapter calls are copied as described above. Filesystem option validation,
lifetime, and composition reside in `engine.go` and are intentionally handed
to Stage 3 rather than inferred from this stage's helper review.
### Verification Performed
The code knowledge graph was used to locate each scoped helper and adapter,
trace its callers and callees, compare public and internal interface widths,
and confirm the duplicated profile rule. Source and focused tests were then
read to verify the graph conclusions.
The following focused commands passed:
```sh
go test . -run 'Test(PublicArtifactReaderAdapterCopiesBody|RunSucceedsWithInjectedLLMClient|RunPassesPreparedRequestToInjectedLLMClient|EngineRunPropagatesCallerCancellation|WithArtifactReaderRejectsNilReader|ArtifactReaderReceivesPublicReferenceAndPreparesArtifact|ArtifactReaderFailuresPreserveArtifactLoadErrors|RunAddsLLMGenerateToCollaboratorPublicError|PublicErrorsSupportErrorsIs|OpenAICompatibleProfileRunsThroughNormalProfilePath|OpenAICompatibleProfileDefersExtraParamsValidation|OpenAICompatibleProfileNestedExtraParamsRunThroughWithProfiles|WithProfilesRejectsDuplicateIDs|WithProfilesRejectsInvalidExtraParams|WithProfilesRejectsCyclicExtraParams|LocalBackendConstructsAndRegistersConventionalBackend|WithBackendCopiesQueueCapacity|BackendRegistrationRejectsInvalidAndDuplicateDefinitions|BackendExtraParamsAreDeeplyCopiedAtConstructionAndLookup|PreparedRunJSONOmitsZeroTimingValues|BackendIdentityJSONNamesAndOmission|PreparedRunJSONTimingRoundTrips|RunResultJSONUsesMillisecondsAndRoundTrips)$'
go test ./internal/profile -run 'Test(FilesystemRepository_GetProfile|FSRepository)$'
go test -race . -run 'Test(EngineRunPropagatesCallerCancellation|ArtifactReaderFailuresPreserveArtifactLoadErrors|PublicArtifactReaderAdapterCopiesBody|OpenAICompatibleProfileNestedExtraParamsRunThroughWithProfiles)$' -count=3
```
A temporary program outside the repository decoded
`{"duration_ms":9223372036854775807}` into `RunResult`; `go run` reported
`error=<nil> duration=-1ms nanoseconds=-1000000`, confirming S02-F01. The
temporary source was removed and no probe output was added to the repository.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
component review.
- Stage 3 owns `NewEngine` option application and the actual composition,
validation, and lifetime of configured filesystems, readers, clients,
default-client configuration, and engine-local backend and capacity
behavior. Focused internal tests own registry normalization, manager policy,
and HTTP-client cloning. S03-F02 identifies the material missing distinctions
rather than recommending duplicate internal choreography tests.
### Verification Performed
The code knowledge graph was used to find `NewEngine`, every option category,
source-assembly helpers, and directly relevant tests; trace construction into
the registry, capacity manager, repositories, validators, model client, and
runner; and confirm that later runtime mechanics were outside the reviewed
path. Important ownership and error conclusions were confirmed against source.
The following focused commands passed:
```sh
go test . -run 'Test(NewEngineRejectsMissingPromptDir|NewEngineAcceptsMissingProfileDir|SourceOptionsRejectInvalidInputs|PackageOptionsComposeFromSlice|RepeatedOptionsUseLastValueInEachCategory|FallbackProfileSourcePrecedence|FallbackProfileSourcePreservesLazyLoadingAndErrors|BackendOptionsAccumulateAndRegistrationsAreEngineLocal|BackendRegistrationRejectsInvalidAndDuplicateDefinitions|BackendExtraParamsAreDeeplyCopiedAtConstructionAndLookup|BackendCapacityIsIndependentBetweenEngines|WithLLMClientRejectsNilClient|WithArtifactReaderRejectsNilReader|PromptRepositoryReadFailureMapsToPromptLoad|SelectedProfileRepositoryReadFailureMapsToProfileLoad|PrepareWorksWithPromptFSAndRelativeContentFile|PrepareWorksWithPromptFile|PrepareWorksWithProfileFSOverBuiltIns|PrepareWorksWithProfileFileOverBuiltIns|RunStructuredOutputWorksWithSchemaFS|RunStructuredOutputWorksWithSchemaFile|EngineRunLayersTransportAndGenerationTimeouts)$'
go test ./internal/backend -run 'Test(RegistryIncludesExactOpenRouterDefinition|RegistryNormalizesUniqueAdditionsAndIsolatesMutations|NewRegistryNormalizesCapacityPolicy)$'
go test ./internal/capacity -run 'Test(NewManagerRejectsInvalidPolicies|ManagerAdmissionIsBoundedAndReleaseIsIdempotent|ManagerAdmissionHonorsContextAndUnlimitedBackends)$'
go test ./internal/llm -run 'TestNewOpenAICompatibleClientDoesNotMutateSupplied(Nonzero|Zero)TimeoutClient|TestNewOpenAICompatibleClientTreatsSuppliedNegativeTimeoutAsUnset'
go test -race . -run 'Test(BackendCapacityIsIndependentBetweenEngines|BackendOptionsAccumulateAndRegistrationsAreEngineLocal|EngineSupportsConcurrentPrepareAndRun|RepeatedOptionsUseLastValueInEachCategory)$' -count=3
```
A temporary program outside the repository created an existing
`prompt.yaml ` file and called `NewEngine` with `WithPromptFile` using that
exact path. Direct `os.Stat` returned nil, while construction returned
`ErrInvalidConfig` after reporting the trimmed `prompt.yaml` path, confirming
S03-F01. The temporary source and generated file were removed.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
component review.
- Stage 4 owns operation entry points and public runtime error/result behavior;
construction tests were read only through the behavior needed to observe
assembled dependencies.
- Stages 6, 7, 8, 10, 14, and 15 own backend policy, prompt sources, profile
repositories, validators, provider transport, and capacity scheduling
respectively. This stage established only that `NewEngine` selects and wires
`InspectPrompt`, or `InspectProfile` functions. There is therefore no second
operation surface whose translation, errors, or ownership can drift from
the methods.
- **Test ownership and duplication:** Root external-package tests protect the
exported facade and representative assembled workflows. Focused internal
tests own runner coordination and public-error translation mechanics. Some
lifecycle and error categories necessarily appear at both levels, but the
assertions address different stable boundaries; no removable semantic
duplication was found. S04-F01 is the one important identity currently
asserted only below the applicable public operation boundary.
- **Clarity and cost:** The operation facade is a uniform sequence of guard,
translation where needed, one delegation, public error mapping, and outward
conversion. No duplicated orchestration policy, repeated I/O, avoidable
copying, or operation-layer complexity was found. Costs inside preparation,
generation, validation, transport, and capacity remain assigned to their
owning later stages.
### Verification Performed
The code knowledge graph was used to find every public engine operation,
confirm their runner and conversion edges, inventory directly relevant root
tests, locate the internal cancellation assertions, and verify that no
package-level operation convenience functions exist. Important context,
error, ownership, and no-partial-result conclusions were confirmed against
source.
The following focused commands passed:
```sh
go test . -run 'Test(PrepareWorksWithFrameworkContractCorpus|RunSucceedsWithInjectedLLMClient|RunPassesPreparedRequestToInjectedLLMClient|EngineRunPropagatesCallerCancellation|ArtifactReaderFailuresPreserveArtifactLoadErrors|RunAddsLLMGenerateToCollaboratorPublicError|PrepareWithoutProfileMatchesSpecificPublicError|RunValidationFailureReturnsResult|PublicErrorsSupportErrorsIs|InspectProfileResolvesCredentialStatesWithoutPromptOrGeneration|InspectProfilePreservesPublicErrorIdentities|InspectProfileReturnsIndependentTargetMatchingPreparation|InspectPromptReturnsDeclaredMetadataWithoutExecutionWork|InspectPromptPreservesPublicErrorIdentities|InspectPromptReturnsIndependentMetadataMatchingPreparation|PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|PreparedExecutionLifecycleAndEngineBinding|PreparedExecutionConcurrentClaimAllowsOneGeneration|PreparedExecutionRunAndDiscardRaceHasOneWinner|PreparedExecutionDiscardAndFormattingDoNotExposePrivateState|PreparedExecutionCredentialCapacityAndTimingBoundaries)$'
go test -race . -run 'Test(EngineRunPropagatesCallerCancellation|InspectProfilePreservesPublicErrorIdentities|InspectPromptPreservesPublicErrorIdentities|PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|PreparedExecutionLifecycleAndEngineBinding|PreparedExecutionConcurrentClaimAllowsOneGeneration|PreparedExecutionRunAndDiscardRaceHasOneWinner)$' -count=3
go test ./internal/usecase -run 'TestRunnerRunCancellationPreservesGenerationCategory'
go test . -run 'Test(MapPublicErrorPreservesGenerationCancellation|MapPublicErrorTranslatesCapacityError)$'
```
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
operation-boundary review.
- Stages 7, 8, 10, 11, 13, 14, and 15 own prompt loading, profile loading,
malformed numbers, and non-finite floats are rejected with a structural
path. The lack of an acyclic traversal bound is S05-F03.
- **Copy cost:** Ordinary accepted trees are visited and allocated once per
occurrence, with sorted map keys making the first reported invalid path
deterministic. Boundary copies occur when caller ownership changes, backend
lookups publish snapshots, prepared execution separates payload and details,
and details are returned. No unnecessary duplicate validation owner was
found, but shared acyclic subgraphs can be expanded repeatedly as recorded
in S05-F03.
- **Test ownership:** Domain session tests own the shared normalization rule;
use-case tests own credential-free prepared construction and frozen
execution; root tests own public snapshots and JSON. JSON-value package tests
correctly use the narrow shared boundary but do not yet discriminate all
supported reflection branches (S05-F04). Internal prepared JSON tests are on
a non-production boundary (S05-F05).
### Verification Performed
The code knowledge graph was used to inventory every declaration and test in
both packages, trace all callers of `NormalizeSessionID`, `Copy`, and
`CopyMap`, and confirm prepared-run/schema clone and serialization ownership.
Important behavior was confirmed against complete package source and tests.
The following focused commands passed:
```sh
go test ./internal/domain ./internal/jsonvalue
go test ./internal/usecase -run 'Test(RunnerDirectSessionResolution|HashRenderedPromptIncludesSessionIDWhenPresent|RunnerPrepareExecutionCompletesWithoutAdmissionOrGeneration|RunnerRunPreparedKeepsDirectCredentialOutOfMetadata|ExecutionProfileToTargetPopulatesAllFieldsAndCopiesExtraParams)$'
go test . -run 'Test(PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|ExtraParamsTypedNestedValuesAreCopiedAcrossPublicBoundary|BackendExtraParamsAreDeeplyCopiedAtConstructionAndLookup|RunRejectsInvalidExtraParams)$'
go test -race ./internal/domain ./internal/jsonvalue -count=3
go test -race . -run 'Test(PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|ExtraParamsTypedNestedValuesAreCopiedAcrossPublicBoundary|BackendExtraParamsAreDeeplyCopiedAtConstructionAndLookup)$' -count=3
```
A temporary program under the repository imported the two internal packages
and confirmed S05-F01, S05-F02, and the 20,000-level acceptance evidence for
S05-F03. It also recorded the current nil-versus-empty behavior for the
coverage ledger. The temporary source and directory were removed before the
audit artifact was edited.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
shared-value review.
- Stage 6 should use the numeric and traversal findings when reviewing backend
extra parameters without repeating the generic copier audit. Stages 10 and
13 own validation-plan construction and prepared-handle lifecycle; they
should treat the schema-copy and credential-redaction behavior recorded here
as established boundary evidence.
- Stage 11 owns runner precedence and execution coordination. The shallow
runner map copies were consulted only to confirm that validated nested values
already have a single owner; their broader merge behavior remains out of
names, trimmed values, and ordinary HTTP and HTTPS endpoints. Backend values
expose no arbitrary header map, so there is no registry-owned header state
to validate or copy; authorization and content-type construction belong to
Stage 14.
- **Parameter validation:** Empty and reserved top-level parameter keys are
rejected before registration. The registry consumes
`llm.IsReservedOpenAIChatRequestField`, while the model client owns and tests
the complete reserved-field list against its actual top-level payload. This
preserves dependency direction and gives the registry one representative
integration case rather than duplicating the transport's list. Recursive
validation and copying remain owned by `internal/jsonvalue`; S05-F02 and
S05-F03 already record its numeric inconsistency and missing traversal bound
and were not repeated here.
- **Capacity policy normalization:** Negative limits and queue capacities,
queues on unlimited backends, and overflowing total capacities are rejected.
A positive limit with no explicit queue receives the documented capacity,
while explicit zero is retained and unlimited backends produce no policy.
Registry policy extraction is correct; permit acquisition, fairness,
cancellation, and runtime bounds remain Stage 15 scope.
- **Default ownership:** The default execution target contains only the
documented 600-second framework baseline; all optional provider controls
remain unspecified. Schema, artifact-name, media-type, timeout, and
OpenAI-compatible path constants are application-neutral library values,
while OpenRouter capacity and connection defaults correctly remain with the
backend registry. The only mutable-default concern is S06-F01.
- **Built-in backend and profile consistency:** All 24 embedded profiles load
through the ordinary repository, have unique nonblank IDs, select the exact
`openrouter` registry ID, and omit endpoint, API-key environment, and raw
API-key fields. Their IDs and model values match the canonical catalog in
`docs/formats.md`. Consumer profiles may intentionally override matching
built-in profile IDs through repository precedence, whereas consumer
backends may not replace the reserved built-in backend ID.
- **Test ownership and cost:** Backend package tests own registry validation,
exact operational OpenRouter policy, copies, lookup errors, and capacity
snapshots. Built-in repository tests own embedded-catalog validity and
backend linkage. LLM tests own the reserved request-field list, and root
tests retain only representative public assembly and copy behavior. No
material redundant validation matrix or missing registry boundary test was
found.
### Verification Performed
The code knowledge graph was used to inventory the three scoped packages,
trace registry and built-in repository assembly, find all consumers of the
defaults, and confirm that the reserved request-field function has exactly the
registry normalizer and provider payload builder as callers. Important
conclusions were confirmed against complete source, tests, embedded profiles,
and canonical documentation.
The following focused commands passed:
```sh
go test -cover ./internal/backend ./internal/defaults ./internal/profile/builtin
go test ./internal/llm -run 'TestOpenAICompatibleClientRejectsInvalidExtraParamsBeforeProviderCall|TestNewOpenAICompatibleClientDoesNotMutateSupplied(Nonzero|Zero)TimeoutClient|TestNewOpenAICompatibleClientTreatsSuppliedNegativeTimeoutAsUnset'
go test ./internal/usecase -run 'Test(ResolveExecutionTargetUsesBackendProfileAndRequestPrecedence|ResolveExecutionTargetDefaultsAndProfileZeros|RunnerInspectProfileResolvesProfileAndBackendOnce)'
go test . -run 'Test(BackendOptionsAccumulateAndRegistrationsAreEngineLocal|BackendRegistrationRejectsInvalidAndDuplicateDefinitions|BackendExtraParamsAreDeeplyCopiedAtConstructionAndLookup|WithBackendCopiesQueueCapacity|PrepareUsesBuiltInProfileWithoutProfileDir|CustomProfileOverridesBuiltInProfile|RunUsesResolvedBackendWithBuiltInLLMClient|EngineExecutionSettingPrecedence)$'
go test -race ./internal/backend ./internal/profile/builtin -count=3
go vet ./internal/backend ./internal/defaults ./internal/profile/builtin
```
The coverage diagnostic reported 94.0% statement coverage for
`internal/backend`, 100.0% for `internal/profile/builtin`, and no direct test
coverage for `internal/defaults`. Coverage alone was not treated as a finding:
the defaults are exercised through the consuming use-case, model-client,
artifact, validator, and root contract tests, and a separate test of constant
declarations would add no behavioral protection.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
registry and defaults review.
- Stage 8 owns general filesystem profile parsing, validation, discovery, and
overlay mechanics. This stage established only that the embedded catalog
supplies valid ordinary profiles tied to the built-in backend.
- Stage 14 owns completion-URL composition, authentication and content-type
headers, payload merging and serialization, deadline behavior, response
handling, and transport resources. It should treat the shared reserved-field
session templates, schema paths, default profiles, cache values, and enum
declarations are normalized or validated into domain values. Inputs remain
ordered and unique after trimming; messages require exactly one inline or
file-backed body; cache control accepts only `ephemeral` with empty or `1h`
TTL; output format, validation mode, schema dependency, and nonnegative
repair attempts are enforced. The material test omissions are S07-F06.
- **Inline and file-backed content:** Inline templates preserve their body
while whitespace-only content is rejected. Selected file-backed bodies are
read eagerly so exact inspection and preparation validate the reference at
the same point-in-time boundary. Containment and exact-name defects are
S07-F01; unrelated eager reads are S07-F04. Rendering syntax and input-helper
behavior remain Stage 9 scope.
- **Source parity and ownership:** Both sources share domain normalization but
duplicate discovery-to-selection orchestration. S07-F05 records the
resulting policy ownership and drift risk. File-catalog helpers remain
appropriately shared with profile and validator packages rather than
embedding prompt-specific behavior.
- **Fixtures and test value:** Static fixtures efficiently cover representative
valid definitions, nested strict YAML, cache control, and content references;
dynamic temporary files cover nesting, ambiguity, and contextual selection.
The `fs.FS` cases add distinct source-containment and parity protection
rather than repeating the full OS fixture matrix. No fixture should be
removed solely for sharing a YAML shape; S07-F06 recommends a compact table
only for currently absent scalar validation branches.
### Verification Performed
The code knowledge graph was used to inventory both packages, trace discovery
and path helpers into prompt, profile, and validator consumers, trace prompt
repository resolution through exact inspection and preparation, and compare
the two source implementations. Important behavior was confirmed against all
source, tests, fixtures, and canonical format and source documentation.
The following focused commands passed:
```sh
go test -cover ./internal/filecatalog ./internal/promptdef
go test ./internal/usecase -run 'Test(RunnerInspectPromptResolvesOneDefinitionWithoutExecutionCollaborators|RunnerInspectPromptClassifiesFailuresWithoutRepositoryWorkAfterCancellation|RunnerPrepareUsesThePromptInspectionSelectionAndHash|RunnerPrepareFileBackedPromptBodiesRenderCorrectly)$'
go test . -run 'Test(InspectPromptReturnsDeclaredMetadataWithoutExecutionWork|InspectPromptPreservesPublicErrorIdentities|InspectPromptReturnsIndependentMetadataMatchingPreparation|PrepareWorksWithPromptFSAndRelativeContentFile|PrepareWithPromptFSRejectsEscapedContentFile|PrepareWorksWithPromptFile|PromptRepositoryReadFailureMapsToPromptLoad)$'
go test -race ./internal/filecatalog ./internal/promptdef -count=3
go vet ./internal/filecatalog ./internal/promptdef
```
The coverage diagnostic reported 92.9% statement coverage for
`internal/filecatalog` and 84.3% for `internal/promptdef`. Coverage output was
used only to locate unexamined decisions; S07-F06 is based on direct comparison
of production validation branches with tests and fixtures.
Temporary package probes, removed before this artifact was edited, confirmed:
- an OS-directory `../outside.txt` content reference returned the outside
sentinel body;
- an existing whitespace-suffixed content filename was changed before lookup;
- malformed `target.yaml` shadowed a valid prompt whose YAML ID was `target`;
- an invalid unrequested version blocked a valid requested version;
- a second YAML document with an unknown field was ignored; and
- a counting filesystem observed one unrelated template-body open per exact
lookup.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
discovery and prompt-definition review.
- Stage 8 owns profile-specific decoding, selection, source parity, and
repository composition. It should reuse the established file-catalog
behavior but independently assess whether profile selection or YAML stream
handling has analogous defects.
- Stage 9 owns ordinary artifact reads and prompt/session rendering, including
template parsing, variables, input helpers, cache-control propagation, and
rendered-message ownership. This stage established only the definition and
syntax, semantic, credential, duplicate, discovery, and read failures retain
useful source-relative paths or directory context. File discovery and the
per-file loop honor context cancellation, and overlays do not fall back
after a cancellation error. Public exact absence remains
`ErrProfileNotFound`, while other repository failures map to
`ErrProfileLoad`.
- **Ownership and immutability:** Each file lookup decodes a fresh domain
profile, so caller mutation is not retained by the repository. The in-memory
adapter stores validated copies and returns a new profile with copied
`extra_params`; overlays do not mutate returned definitions. Resolution
and public conversion create later copies, with runtime override and backend
merging deferred to Stage 11. The invalid source values in S08-F01 and
S08-F02 must be rejected before those immutable snapshots are created.
- **Repeated work:** Point-in-time inspection, preparation, and execution
intentionally perform fresh source lookup, and no stale repository cache was
found. Each YAML file is read once per consulted source lookup. The
additional catalog-wide decoder pass is the avoidable work in S08-F06.
- **Test ownership:** Repository tests own YAML selection, source recursion,
raw-key rejection, profile validation, duplicates, and overlay semantics.
Root tests own option composition, complete precedence, lazy source access,
and public error translation. Use-case inspection tests own one exact
repository lookup and collaborator-free inspection behavior. No material
high-level repetition of the full parser matrix was found; the missing
regression cases are tied directly to the accepted findings above and the
established S02-F02 boundary table.
### Verification Performed
The code knowledge graph was used to inventory the scoped package, trace both
source constructors and overlay construction into `NewEngine`, trace profile
lookups into exact inspection and preparation, and identify all consumers of
`domain.ExecutionProfile`. Important conclusions were confirmed against the
complete source, repository tests, profile fixtures, public GoDoc, and
canonical profile and source contracts.
The following focused commands passed:
```sh
profile_audit_cover=$(mktemp)
go test -coverprofile="$profile_audit_cover" ./internal/profile
go tool cover -func="$profile_audit_cover"
rm "$profile_audit_cover"
go test ./internal/usecase -run 'TestRunnerInspectProfile'
go test . -run 'Test(CustomProfileOverridesBuiltInProfile|MalformedCustomProfileDoesNotFallbackToBuiltIn|PrepareWorksWithProfile(FS|File)OverBuiltIns|FallbackProfileSource(Precedence|PreservesLazyLoadingAndErrors|WorksAcrossWorkflows)|SelectedProfile(RawAPIKey|InvalidYAML|RepositoryReadFailure)MapsToProfileLoad)$'
go test -race ./internal/profile -count=3
go vet ./internal/profile
```
The coverage diagnostic reported 85.6% statement coverage for
`internal/profile`; `validateProfile` reported 66.7%. Coverage was used only
to find decisions for direct inspection. The accepted findings are based on
source traces and reproduced behavior, not the percentages.
Temporary package probes, removed before this artifact was edited, confirmed:
- malformed `target.yaml` with a different YAML ID shadowed a valid exact
definition;
- a second YAML document containing an unknown field was ignored;
- NaN temperature and top-p values passed profile validation;
- an empty-key, NaN-bearing `extra_params` map loaded and then failed JSON
serialization; and
- a whitespace-bearing YAML ID was absent under the normalized public lookup
identity.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
profile-source review.
- S02-F02 already owns consolidation of file and in-memory profile semantic
validation. S08-F01 and S08-F02 supply confirmed correctness requirements
for that shared owner rather than creating a second duplication finding.
failures, unknown inputs, empty roles, empty sessions, and overlong sessions
return no partial prompt. Context responsiveness is incomplete as S09-F03
records.
- **Cache control and ownership:** Each non-nil cache-control value is copied
into its rendered message, and nil remains nil. Rendered message storage and
buffers are operation-local; later source mutation cannot change an already
prepared prompt.
- **Repeated work:** Artifacts are read and hashed once each before the
renderer boundary, and each distinct session or message template is parsed
once in one render. Point-in-time definitions make cross-operation parse
caching a different lifetime decision with no demonstrated need. Repeated
input-helper body conversions are the measured waste in S09-F04.
- **Diagnostics and determinism:** Error text identifies the input name,
message index, or file path needed to diagnose the failure without embedding
bodies or variable values. Input map iteration occurs in the runner rather
than either scoped package and was not audited here. Rendered order follows
definition order and no shared mutable package state was found.
- **Test ownership:** Artifact package tests own dispatch, materialization,
metadata, ownership, and focused failures; renderer tests own templates,
inputs, variables, sessions, roles, and cache control. Use-case tests own
error categorization and the real file-content-to-render integration. The
renderer subtest labelled file-backed receives already loaded `Content` and
cannot exercise `ContentFile`; it is small overlap, while the use-case test
provides the actual boundary protection. Exact opaque hash coupling is the
actionable test friction in S09-F05.
### Verification Performed
The code knowledge graph was used to inventory both scoped packages, trace
`Reader.Read` and `Renderer.Render` into preparation, identify their complete
focused test surfaces, and confirm that materialization and rendering have one
production consumer. The full package source and tests were then checked
against public GoDoc, format and source contracts, and the architecture and
testing policies.
The following focused commands passed:
```sh
artifact_audit_cover=$(mktemp)
go test -coverprofile="$artifact_audit_cover" ./internal/artifact
go tool cover -func="$artifact_audit_cover"
rm "$artifact_audit_cover"
prompt_audit_cover=$(mktemp)
go test -coverprofile="$prompt_audit_cover" ./internal/prompt
go tool cover -func="$prompt_audit_cover"
rm "$prompt_audit_cover"
go test ./internal/usecase -run 'Test(RunnerDirectSessionResolution|RunnerPrepareFileBackedPromptBodiesRenderCorrectly|RunnerPrepareRequiredInputMissingFails|RunnerPrepareUnknownTemplateInputReferenceFails|RunnerRunArtifactLoadFailure|RunnerRunPromptRenderFailure|HashRenderedPromptIncludesCacheControlWhenPresent|HashRenderedPromptIncludesSessionIDWhenPresent)$'
go test . -run 'Test(PublicArtifactReaderAdapterCopiesBody|PrepareWorksWithInlineInputs|EngineRunWithDirectorySourcesAndFileInputs|ArtifactReaderReceivesPublicReferenceAndPreparesArtifact|ArtifactReaderFailuresPreserveArtifactLoadErrors)$'
go test -race ./internal/artifact ./internal/prompt -count=3
go vet ./internal/artifact ./internal/prompt
```
The coverage diagnostics reported 89.7% statement coverage for
`internal/artifact` and 93.3% for `internal/prompt`. Coverage was used only to
locate unexercised decisions for direct inspection; the accepted findings rest
on source traces, contract comparison, reproduced behavior, and a focused
allocation measurement.
Temporary package probes, removed before this artifact was edited, confirmed:
- empty inline content was rejected while an empty file loaded successfully;
- canceling an in-progress FIFO read did not return until a writer externally
released it, after which the canceled read returned success;
- a pre-canceled render parsed an invalid session and returned the template
error before observing cancellation; and
- rendering a 1 MiB artifact through the input helper allocated approximately
one additional body-sized buffer compared with equivalent string template
data.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
and compilation failures with useful paths or schema locations. Public
GoDoc warns that validation errors may contain sensitive output-derived
data. Mode, schema path, status, validity, and attempts fields are copied
into fresh result values, and use-case tests own the actual repair-attempt
override without making repair policy part of this pass.
- **Test ownership:** Validator tests own modes, source mechanics, schema
compilation, references, dialects, result classification, and frozen-plan
source independence. Use-case tests own loader/preparer selection,
structured-output derivation, error categorization, and plan retention.
Root tests own configured source composition, public ownership, and result
translation. The missing numeric, compilation-parity, cancellation, and
allocation cases map directly to S10-F01, S10-F03, S10-F04, and S10-F05;
the `%zz.json` test currently preserves S10-F02 rather than a contract.
### Verification Performed
The code knowledge graph was used to inventory the validator package, locate
all mode and source entry points, trace schema document loading and validation
preparation into the use case, and identify the frozen plan's execution and
structured-output consumers. Same-named validator methods that the graph
conflated were read directly, together with every focused test, the framework
schema fixture, public GoDoc, and the canonical format and internal source
contracts.
The following focused commands passed:
```sh
validation_audit_cover=$(mktemp)
go test -coverprofile="$validation_audit_cover" ./internal/validate
go tool cover -func="$validation_audit_cover"
rm "$validation_audit_cover"
go test ./internal/usecase -run 'Test(RunnerPrepareJSONSchemaBuildsStructuredOutputSpec|RunnerPrepareJSONSchemaSchemaLoadFailureReturnsValidationError|RunnerRunJSONSchemaSchemaLoadFailureFailsBeforeLLM|RunnerPrepareExecutionCompletesWithoutAdmissionOrGeneration|RunnerRunPreparedUsesFrozenValidationForInitialAndRepairOutputs|RunnerPrepareExecutionRequiresValidationPreparer|RunnerPreparedExecutionWithoutValidatorSkipsValidation)$'
go test . -run 'Test(PrepareWorksWithFrameworkContractCorpus|RunStructuredOutputWorksWithSchemaFS|RunStructuredOutputWorksWithSchemaFile|PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|EngineValidationIsSinglePass)$'
go test -race ./internal/validate -count=3
go test -race . -run 'Test(PreparedExecutionFreezesSourcesAndReturnsIndependentDetails|RunStructuredOutputWorksWithSchemaFS|RunStructuredOutputWorksWithSchemaFile)$' -count=3
go vet ./internal/validate
```
The repository-wide `go test ./...`, `go test -race ./...`, `go vet ./...`,
and `go run ./examples/go-library/prepare` checks also passed.
The coverage diagnostic reported 79.0% statement coverage for
`internal/validate`; prepared-plan construction reported 68.0% for the OS
source and 70.0% for `fs.FS`. Coverage was used only to locate decisions for
direct inspection. Findings are based on contracts, source and call-path
traces, reproduced behavior, and the allocation benchmark rather than the
percentages.
Temporary probes, removed before this artifact was edited, confirmed:
-`json` mode rejected syntactically valid `1e400`, and JSON Schema validation
treated the distinct integers `9007199254740992` and `9007199254740993` as
equal;
- both OS and `fs.FS` validators found and decoded `%zz.json` but failed when
its path was parsed as a compiler URL;
- ordinary `Prepare` published an invalid keyword and a missing reference that
`PrepareExecution` rejected;
- one ordinary JSON Schema run read the root document twice;
- cancellation waited for a blocked schema filesystem, while cancellation
during schema execution was ignored and returned a passed result;
- a 32-worker prepared-plan validation probe passed three race-enabled runs;
and
- JSON-only validation of an approximately 1 MiB value allocated about
22.7 MiB in 250,031 allocations, versus zero allocations for a syntax-only
scan.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
validation review.
- S07-F01 already owns exact-path alteration in the shared file-catalog helper;
its effect on directory-backed schema paths is recorded here without a
duplicate finding. S10-F02 is the separate compiler-URL encoding defect.
- Stage 11 owns effective output-contract selection and preparation fidelity.
It should treat the compiled-plan and root-document invariants recorded here
as established inputs when comparing inspection and preparation.
numeric request values and missing credentials remain invalid requests; and
schema preparation remains a validation operation. No new error-identity
defect was found apart from the invalid values accepted by S11-F01 and
S11-F02.
- **Duplication and test ownership:** Selection, hashing, profile/backend
resolution, target merging, and structural target validation each have one
use-case owner shared by inspection and preparation. Root tests own public
mapping, source assembly, and mutation independence; focused use-case tests
own collaborator call counts, merge rules, and operation categories. No
duplicate finding was warranted. S02-F02 and S08-F01 already establish that
profile acceptance itself needs a shared domain owner; Stage 17 can decide
whether runtime numeric and output-contract validation should join the same
source-neutral validation boundary.
### Verification Performed
The code knowledge graph inventoried every function in the three scoped files,
traced the shared helpers inbound from inspection and all preparation entry
points, and traced their default, backend, profile, request, credential,
output-contract, renderer, schema, and snapshot consumers. Source was then read
for every scoped helper and focused test, together with public GoDoc, the
framework format reference, the package consumer guide, internal runner and
architecture documents, and prior audit handoffs.
The following focused commands passed:
```sh
go test ./internal/usecase -run 'Test(RunnerInspectPrompt|RunnerInspectProfile|RunnerPrepare|ResolveExecutionTarget|MergeExecutionTarget|ExecutionProfileToTarget)' -count=1
go test . -run 'Test(InspectPrompt|InspectProfile|EngineExecutionSettingPrecedence|CustomBackendFlowsThroughProfilesOverridesAndInjectedClient|PreparedExecutionFreezesSourcesAndReturnsIndependentDetails)' -count=1
resolution_audit_cover=$(mktemp)
go test -coverprofile="$resolution_audit_cover" ./internal/usecase
go tool cover -func="$resolution_audit_cover"
rm "$resolution_audit_cover"
go vet ./internal/usecase .
```
The repository-wide `go test ./...`, `go test -race ./...`, `go vet ./...`,
and `go run ./examples/go-library/prepare` checks also passed. The coverage
diagnostic reported 90.3% statement coverage for `internal/usecase`; coverage
was used only to locate unexercised resolution branches, not as evidence by
itself.
A temporary public-package probe, removed before this artifact was edited,
confirmed that:
-`Prepare` accepted NaN temperature and top-p pointers and returned both NaN
values in `EffectiveModelParams`; and
-`Prepare` and `PrepareExecution` accepted format `binary` and validation mode
`unknown` and preserved both unsupported values in their returned details.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
and result metadata. Root tests own public error mapping, one-pass public
validation, and consumer-visible result behavior. Validation packages own
content rules, while transport and capacity packages own their injected
mechanics. S12-F01, S12-F02, and S12-F03 identify the repair-specific
fidelity, accounting, and retry cases missing from that otherwise clear
ownership split.
### Verification Performed
The refreshed code knowledge graph inventoried the scoped symbols, traced the
ordinary `Run` path into `executePreparedRun`, confirmed the helper's two
callers, and located the repairer and capacity-error consumers. Every scoped
transition and focused ordinary-run test was then checked in source against
the public GoDoc, internal runner contract, policy documents, and Stage 10 and
11 handoffs.
The following focused commands passed:
```sh
go test ./internal/usecase -run 'TestRunner(RunSuccessful|RunPassesExtraParamsToGenerateRequestTarget|AdmissionFailureSkipsCompletionCollaborators|ReleasesAdmissionAcrossRunOutcomes|RunArtifactLoadFailure|RunPromptRenderFailure|RunLLMFailure|RunCancellationPreservesGenerationCategory|RunLLMInvalidRequestMapsToUsecaseInvalidRequest|RunValidationStillWorks|RunStructuredRepairRemainsBoundedAndUsesEffectiveModelSettings|SchedulesInitialAndRepairGenerationThroughOneBackendPool|RunRepairCarriesEffectiveSessionID|RunJSONSchemaRepairCarriesStructuredOutputSpec|RunJSONSchemaSchemaLoadFailureFailsBeforeLLM)$' -count=1
go test . -run 'Test(RunSucceedsWithInjectedLLMClient|EngineRunWithDirectorySourcesAndFileInputs|RunPassesPreparedRequestToInjectedLLMClient|EngineRunPropagatesCallerCancellation|RunAddsLLMGenerateToCollaboratorPublicError|RunValidationFailureReturnsResult|EngineValidationIsSinglePass|CapacityExceededSentinelContract|MapPublicErrorTranslatesCapacityError)$' -count=1
body omission and encoding, timeout layering, response mapping, package
errors, closure, and framing. Root tests appropriately own only resolved
backend fields reaching the built-in transport, reserved-field rejection at
the public operation boundary, and framework/caller timeout composition.
Those cross-layer assertions are not duplicates of transport mechanics.
S14-F06 records the mechanical duplication within the owning transport file.
### Verification Performed
The code knowledge graph inventoried every production and test symbol in
`internal/llm`, identified `Generate` and construction as the only transport
hotspots, and traced the generation boundary back to engine assembly and
ordinary/prepared execution. All important graph conclusions were confirmed
against source, GoDoc, the integration contract, the internal model-client
document, and the Stage 12 and 13 handoffs.
The focused package suite passed with 92.2% statement coverage; coverage was
used only to locate unexercised response and defensive branches:
```sh
llm_audit_cover=/tmp/promptkit-llm-audit.cover
go test -coverprofile="$llm_audit_cover" ./internal/llm
go tool cover -func="$llm_audit_cover"
```
The following focused repeated and race-enabled checks and the repository-wide
ordinary suite also passed:
```sh
go test -race ./internal/llm -count=10
go test -race . -run 'Test(EngineRunPropagatesCallerCancellation|RunRejectsReservedExtraParamsBeforeProviderCall|RunUsesResolvedBackendWithBuiltInLLMClient|EngineRunLayersTransportAndGenerationTimeouts)$' -count=3
go test ./...
```
Temporary package probes, removed before this artifact was edited, confirmed
that:
- a canceled outbound request matched `ErrRequestFailed` but not
`context.Canceled`;
-`math.MaxInt` timeout seconds produced a deadline approximately one second
in the past;
- a query-bearing base sent the completion suffix as query data while
returning success;
- a valid response with a 2 MiB content string was fully accepted; and
- a valid response object followed by non-JSON text returned content and no
error.
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
transport review.
- Stage 15 should treat each call into the client as one non-retrying outbound
operation. Capacity wrapping must preserve the context identities required
by S14-F01 but does not own URL, body, or response mechanics.
- Stage 16 should use this stage's test-ownership map rather than duplicating
the provider-wire matrix in root consumer workflows. S14-F06 is the scoped
candidate for simplifying the transport suite while retaining its
`httptest` boundary.
- Stage 17 may reconsider extra-parameter validation marshaling only if a
representative benchmark or payload model establishes material cost; this
stage found no standalone efficiency defect there.
go test -coverprofile="$capacity_audit_cover" ./internal/capacity
go tool cover -func="$capacity_audit_cover"
```
The following focused ordinary, race-enabled, and repeated checks also passed:
```sh
go test ./internal/capacity ./internal/usecase . -run 'Capacity|Admission|SchedulesInitialAndRepairGenerationThroughOneBackendPool|ReleasesAdmission|UnlimitedBackends|PreparedExecutionCredentialCapacity'
go test -race ./internal/capacity ./internal/usecase . -run 'Capacity|Admission|SchedulesInitialAndRepairGenerationThroughOneBackendPool|ReleasesAdmission|UnlimitedBackends|PreparedExecutionCredentialCapacity'
go test ./internal/capacity ./internal/usecase . -count=50 -run 'Capacity|Admission|SchedulesInitialAndRepairGenerationThroughOneBackendPool|ReleasesAdmission|UnlimitedBackends|PreparedExecutionCredentialCapacity'
```
The repository-wide ordinary and race-enabled suites and the maintained
offline consumer workflow passed as well:
```sh
go test ./...
go test -race ./...
go run ./examples/go-library/prepare
```
### Handoff
- The Stage 0 baseline remains absent and was not backfilled during this
concurrency review.
- Stage 16 can treat admission, backend selection, and generation scheduling
as one engine-local boundary with no accepted defect. Consumer tests should
assert only visible capacity behavior and should not reproduce mutex or
waiter-list mechanics.
- Stage 17 has no capacity-specific optimization candidate from this review.
Any future change to fairness or allocation strategy should first preserve
the current linearization points and be justified by representative
Large files were not treated as defects by size. `engine_test.go`,
`internal/usecase/runner_test.go`, and the external prepared contracts organize
many distinct public or orchestration behaviors, while S14-F06 already records
the one confirmed case where repeated transport scaffolding obscures its
behavior matrix. The 25 ms prepared-timing sleep is unnecessary for ordering
but passed shuffled repetition and race runs, adds negligible suite time, and
does not establish a consequential flaky boundary by itself.
### Risk-To-Owner Matrix
| Risk | Credible current owner | Accepted gap or retained protection |
| --- | --- | --- |
| Public compatibility and error identity | External-package root tests in `engine_test.go`, `public_contract_test.go`, `prepared_execution_contract_test.go`, and `capacity_contract_test.go`; focused internal mapping tests own internal-type containment. | S01-F01, S02-F03, S02-F04, S03-F02, S04-F01, and S13-F01 already identify the consequential missing public cases. Other internal/root overlap asserts different stable boundaries and is retained. |
| Parsing, validation, and serialization | `internal/promptdef`, `internal/profile`, `internal/filecatalog`, `internal/jsonvalue`, `internal/validate`, and domain tests own focused rules; root corpus and JSON contracts own assembled public compatibility. | S05-F04 and S07-F06 own material missing rule coverage. The reproduced parser, profile, schema, and numeric defects already specify regression cases in their component findings; no second suite-level test owner is needed. |
| Immutability and data integrity | Domain and JSON-value tests own shared transforms; backend, repository, use-case, prepared, and root tests own snapshots at each ownership transfer. | S02-F03 owns injected-client mutation isolation. S05-F03 owns unbounded tree work. S05-F05 identifies unused internal prepared JSON tests whose stable public serialization remains protected by external root contracts. |
| External wire behavior | `internal/llm` owns realistic `httptest` request/response behavior; root tests own resolved settings reaching the built-in client and public error mapping. | S14-F01 through S14-F05 own missing cancellation, timeout, URL, size, and framing boundaries. S14-F06 retains protocol assertions while consolidating repeated scaffolding. S16-F02 is the only fixed-port/live-environment case. |
| Cancellation, failure propagation, and recovery | Artifact, validator, model-client, capacity, use-case, prepared-lifecycle, and root tests each own failures at their narrow boundary; root tests own public identities and partial-result rules. | S04-F01, S09-F02, S10-F04, and S14-F01 identify missing or defective cancellation paths. Existing failure tests use `errors.Is`/`errors.As`; error-text checks are limited to required path association, redaction, or diagnostic fragments. |
| Concurrency and resource lifecycle | Capacity package and public capacity contracts own relational limits and FIFO release; prepared use-case and public contracts own claim/discard races; race-enabled validation owns frozen-plan safety. | Stage 15 found no scheduling defect or duplicate owner. S05-F03 and S14-F04 own the two unbounded resource paths. Shuffled repeated race runs found no shared-state or ordering failure. |
| Representative assembled consumer workflows | Root external tests own broad assembled behavior; the framework corpus owns a realistic prepare fixture; the two examples own independently copyable offline preparation and execution programs. | S16-F01 records that only the preparation example is executed by maintainer validation. The examples' small parallel fixtures are retained because each program demonstrates a distinct workflow and remains standalone. |
### Suite And Fixture Ledger
- **Inventory and boundaries:** The graph and source inventory found 25 test
files with 281 top-level tests. Five root files use package
`promptkit_test` for public contracts, while the two small root internal
files directly own adapter copying and error translation unavailable through
an external surface. Internal packages test their own boundaries. No test
imports a consumer, and the AST-based architecture guard recursively rejects
imports of the former consumer module while a focused self-test proves that
its detector finds nested imports.
- **Fixtures and secrets:** Parser and profile fixtures are minimal malformed
and valid YAML cases; schema and prompt content use synthetic values. The
framework corpus is a shared root integration fixture rather than a second
parser truth table. Tests use `t.TempDir`, temporary directories, `fstest`,
and `httptest` where mutable or external behavior matters. Environment
credentials are synthetic and controlled with `t.Setenv` or deliberate
execution-time removal; no real secret or mutable external service is
required. S16-F02 is the sole contacted fixed port.
- **Assertions and coupling:** Public and collaborator errors are normally
asserted with `errors.Is` or `errors.As`. Remaining text assertions select
structural paths, schema/compiler causes, status codes, redaction sentinels,
or the smallest diagnostic fragment needed to distinguish a case; none
snapshots a complete noncontractual message. Exact collaborator call counts
in runner and prepared tests protect ordering, bounded generation, no partial
work, and one-attempt lifecycle requirements rather than private call graphs.
No golden files or automatic update mode exist.
- **Consolidation:** Component ledgers found intentional relational overlap
between package, use-case, and public boundaries. The accepted deletion or
consolidation candidates already state their remaining protection:
S05-F05 can remove unused internal prepared serialization cases while root
JSON contracts remain; S09-F05 can stop pinning a hash algorithm while
retaining determinism and mutation sensitivity; and S14-F06 can share HTTP
setup while retaining every wire-visible assertion. No additional
evidence-backed deletion emerged at suite level.
- **Determinism and cost:** Twenty shuffled ordinary runs and three shuffled
race-enabled runs passed across every package. No test-order, global-state,
data-race, deadlock, or leaked-waiter symptom appeared. A diagnostic timing
run found no individual test above 50 ms in that sample and no package pass
event above 205 ms. Package coverage ranged from 69.2% to 100% among
packages containing substantive tests; the lower percentages align with
the already recorded JSON-value and validation decisions and were not used
as independent findings. `internal/defaults`
remains untested because its trivial baseline is exercised relationally by
higher owners rather than pinned as private constants.
- **Maintained examples:** Preparation resolves and renders without a model;
execution injects a deterministic client and validates a result. Preparation
never calls its configured endpoint, and execution's injected client bypasses
its endpoint, so both remain offline and credential-free.
Their similar prompt files are intentionally local so either complete
program can be copied without a hidden cross-example dependency. Both ran
successfully during this review; only validation ownership is deficient as
S16-F01 records.
### Verification Performed
The code knowledge graph inventoried test files and symbols, associated tests
with production hotspots, and confirmed the external and internal package
boundaries. Source and the prior component ledgers supplied the behavioral
ownership analysis. Diagnostic coverage and timing were used only to direct
the review:
```sh
go test -cover ./... -count=1
go test -json ./... -count=1
```
The suite passed shuffled repetition, shuffled race execution, vet, build, Go
formatting, and both offline example runs:
```sh
go test ./... -shuffle=on -count=20
go test -race ./... -shuffle=on -count=3
go vet ./...
go build ./...
go run ./examples/go-library/prepare
go run ./examples/go-library/run
```
A temporary Python standard-library server was bound to `127.0.0.1:9999` only
for the focused probe. With it active, this command failed with status 501
instead of the expected `ErrRequestFailed`, confirming S16-F02; the server was
stopped immediately afterward:
```sh
go test ./internal/llm -run '^TestOpenAICompatibleClientAllowsEmptyConfiguredBaseURL$' -count=1
```
### Handoff
- The Stage 0 baseline and its assigned comparison of validation-command
owners remain absent and were not backfilled.
- Stage 17 should use the risk matrix and existing S02-F02, S02-F05, S07-F05,
S12-F01, and S14-F06 duplication evidence without treating file size, helper
counts, or intentional cross-boundary tests as new consolidation findings.
- Stage 18 should retain both S16 findings unless the final audited tree has
gained deterministic execution-example validation or removed the fixed-port
assumption. Its synthesis should count earlier test gaps once at their
owning component rather than cloning them from this matrix.
(`resolveOutputContract` and structured-output resolution),
`internal/domain/domain.go` (`OutputContract` and its enums), and the public
`OutputContract` conversion in `convert.go`
- **Contract at issue:** Supported format and validation-mode membership,
non-negative repair attempts, and the JSON-Schema path relationship describe
one `domain.OutputContract`. Prompt-file requirements and request defaults
can differ, but a request replacement must not create a domain value that
the prompt source would reject under the same stable vocabulary.
- **Evidence:** Prompt normalization owns private enum predicates and rejects
unsupported formats, unsupported modes, a missing JSON-Schema path, and
negative repair attempts. Request resolution copies the same domain value
wholesale and defaults only an empty format. S11-F02 confirmed that both
public preparation APIs accept unknown request enums. Source inspection also
shows that a negative request repair count bypasses the prompt-owned
non-negative repair-count rule, and missing request schema information is
left to later schema work and its different error category. The format reference
declares the same output-contract value set before describing complete
request replacement, so this is a split semantic owner rather than two
provider-specific policies.
- **Failure mode:** File and request forms of the same contract have different
acceptance behavior, preparation can publish unsupported stable metadata,
and adding a format or validation mode requires source and orchestration
edits that have no shared compile-time or test owner. A direct fix to
S11-F02 that copies the prompt package's switches would deepen that drift.
- **Recommended direction:** Put source-neutral output-contract predicates and
cross-field invariants in `internal/domain`. Keep file-required fields and
YAML error context in `internal/promptdef`; keep the request's documented
empty-format default and invalid-request translation in `internal/usecase`;
and keep schema loading and compilation in `internal/validate`. Both current
consumers already depend on the domain leaf, so the shared dependency stays
inward without making prompt loading depend on orchestration or validation.
- **Required verification:** Run one shared table over every supported enum,
empty and unknown values, negative and non-negative repair counts, and
schema-path relationships. Retain source-specific prompt cases and require
`Prepare`, `Run`, and `PrepareExecution` request replacements to fail as
invalid requests before source completion, admission, or generation. Valid
contracts must normalize identically across both public preparation paths.
### Retained Cross-Cutting Opportunities
The following accepted component findings already identify the correct owner
or a decision-complete consolidation. They remain accepted without new IDs:
- S02-F05 owns stable public JSON field mapping. Its repeated declarations are
one serialization policy; a wire alias or embedded representation can make
ordinary fields compile-time shared while keeping timing exceptions local.
- S07-F05 owns prompt selection across OS and `fs.FS` repositories. A source
adapter can leave real opening and display-path mechanics at the edge while
`internal/promptdef` owns one selector and normalizer.
- S08-F02 should make file profiles consume the existing
`internal/jsonvalue` invariant owner. The dependency is already valid for
other profile ingress; creating another JSON-shape validator is not needed.
- S12-F01 owns initial-versus-repair generation request construction. The two
calls follow one effective target policy, and a use-case-local request
constructor can share presence, credentials, backend identity, and
structured output without moving provider mapping out of `internal/llm`.
- S14-F06 owns repeated transport test scaffolding. A recording-provider
fixture belongs in the LLM test package and should consolidate mechanics,
not protocol assertions.
### Efficiency Disposition
No new efficiency finding was accepted. The demonstrated opportunities remain
owned by their component findings with the following cross-cutting cost and
verification constraints:
| Finding | Frequency and scale | Evidence and remediation invariant |
| --- | --- | --- |
| S07-F04 | Every exact prompt lookup used by inspection, preparation, and ordinary execution; cost currently scales with all unrelated file-backed template bytes. | A counting filesystem observed one unrelated body open per lookup. Preserve point-in-time YAML scanning and duplicate detection while proving only selected content is opened once. |
| S08-F06 | Every profile lookup, for every YAML file in every consulted overlay source; cost scales with total catalog YAML bytes. | Source inspection confirms two decoder passes per file. Benchmark small and large catalogs with allocation counts, and preserve strict selected-file and repeated point-in-time behavior. |
| S09-F04 | Every `input` helper reference during rendering; cost scales with artifact bytes times references across the session and messages. | The 1 MiB probe measured approximately one additional body-sized allocation per reference. Benchmark one and repeated references while preserving exact bytes and per-render ownership. |
| S10-F03 | Every ordinary JSON-Schema preparation or run; cost scales with the root and transitive schema graph. | A counting source observed the root read twice in ordinary execution, and compiled-plan parity is also a correctness requirement. Prove each schema document is read once per operation without adding a cross-operation cache. |
| S10-F05 | Every generated artifact validated in JSON mode; cost scales with output bytes and nesting. | The approximately 1 MiB probe measured about 22.7 MiB and 250,031 allocations for a discarded tree versus a zero-allocation syntax scan. Retain scalar, object, large-array, trailing-data, and exact-number benchmarks and semantics. |
The Stage 15 concurrency review found no avoidable lock contention or serial
work. Admission is a constant-time locked count update, generation locks cover
only pool bookkeeping, provider calls run unlocked, and separate backends use
separate pools. No scheduling change is justified without representative
contention measurements that preserve the documented FIFO and cancellation
linearization points.
The model-client extra-parameter path validates values before marshaling the
whole request, so it can traverse that subgraph twice. As recorded in Stage
14, no representative measurement established material cost relative to a
provider call; it remains rejected as a standalone efficiency finding pending
a benchmark over realistic parameter sizes. JSON-value defensive copies at
public/internal ownership transfers are likewise contract work, not removable
overhead. S05-F03 already owns their missing depth and work bounds.
### Rejected Candidates
- **Facade method similarity:** The graph scored `Prepare` and `Run` as
identical and the two inspection methods nearly so. These are distinct
relationships, and 53 structural-similarity edges. Its public entry points,
package boundaries, dependency direction, and hotspots remain consistent with
the Stage 17 architecture review. Exact source checks reconfirmed the two
cross-cutting merge groups below. Every retained finding has either confirmed
runtime evidence or high-confidence source, contract, and test evidence; no
medium- or low-confidence observation enters the final accepted set.
### Merge And Supersession Registry
The audit history is preserved in place. One exact policy-duplication record is
superseded, while source-specific behavioral symptoms remain visible under
their shared root causes:
| Canonical group | Historical records | Final disposition |
| --- | --- | --- |
| S17-F01, execution-setting acceptance | S02-F02, S08-F01, S11-F01, S17-F01 | S02-F02 is superseded by S17-F01 because both identify the same missing shared profile/execution-setting owner. S08-F01 and S11-F01 remain accepted downstream correctness evidence for profile and request ingress, respectively. The group is counted once as high-severity correctness, with duplicated policy as its root cause. |
| S17-F02, output-contract legality | S11-F02, S17-F02 | S17-F02 owns the split source-neutral policy; S11-F02 remains the confirmed request-boundary symptom and its error-ordering regression requirement. The group is counted once as medium-severity correctness. |
The other 47 historical IDs remain standalone canonical findings. Similar
effects in separate owners, such as additional YAML documents in prompt and
profile parsers or cancellation in artifact, validation, and transport
boundaries, were not merged: each requires a distinct package fix, preserves a
different error boundary, and has its own regression owner. Keeping those
records separate avoids speculative centralization while still allowing a
later implementation plan to schedule related work together.
After supersession there are 52 accepted evidence records and one superseded
record. After the two root-cause groups are counted once rather than counting
their downstream evidence again, the final planning input contains 49
canonical remediation groups.
### Final Finding Counts
| Category | Canonical findings |
| --- | ---: |
| Correctness | 27 |
| Testing | 13 |
| Efficiency | 4 |
| Duplication | 2 |
| Contract-documentation consistency | 2 |
| Clarity | 1 |
| **Total** | **49** |
| Severity | Canonical findings |
| --- | ---: |
| High | 7 |
| Medium | 36 |
| Low | 6 |
| **Total** | **49** |
The canonical groups comprise 33 confirmed and 16 high-confidence findings.
High severity is reserved for unbounded work or input, source containment,
unresponsive cancellation, data-semantic corruption, and public transport
failure. Medium severity covers bounded but material correctness,
compatibility, policy-drift, test-protection, and measured cost risks. Low
severity is limited to clarity, deterministic workflow protection, and test
maintenance. These ratings describe consumer or maintainer impact, not the
estimated size of a fix.
### Canonical Finding Registry And Recommended Order
This ordering is a risk and dependency sequence for later planning, not an
implementation roadmap. The separate implementation pass must decide work
units, exact files, acceptance criteria, and validation.
| Order | Work class | Canonical IDs | Dependency rationale |
| ---: | --- | --- | --- |
| 1 | High-impact behavioral, data-integrity, resource, and cancellation fixes | S05-F03, S07-F01, S09-F02, S10-F01, S17-F01 (including S08-F01 and S11-F01), S14-F01, S14-F04 | Establish bounds, containment, exact data semantics, shared numeric invariants, and cancellation/resource identities before refactoring or optimizing their paths. |
| 2 | Medium behavioral fixes in public values, normalization, and sources | S02-F01, S03-F01, S05-F01, S07-F02, S07-F03, S08-F02, S08-F03, S08-F04, S08-F05, S09-F01, S09-F03 | Stabilize source selection, parsing, value shape, and error behavior before source consolidation and traversal optimization. S08-F02 should consume bounded shared JSON-value validation after S05-F03. |
| 3 | Medium behavioral fixes in validation, orchestration, and transport | S10-F02, S10-F03, S10-F04, S17-F02 (including S11-F02), S12-F01, S12-F02, S14-F02, S14-F03, S14-F05 | Normalize contracts before schema work, establish one valid compiled schema path, preserve initial/repair semantics, and fix transport framing before reorganizing tests or measuring residual cost. |
| 4 | Contract and documentation consistency decisions | S05-F02, S13-F01 | Decide the public numeric acceptance rule before changing JSON-value boundaries; align copied-handle formatting with the already documented opaque contract. These are confirmed mismatches, not speculative documentation cleanup. |
| 5 | Safe production refactors with clear owners | S02-F05, S07-F05 | Consolidate stable JSON field ownership and prompt source-neutral selection only after their current behavior and defects are fixed and protected. |
| 6 | Consequential medium test gaps | S01-F01, S02-F03, S02-F04, S03-F02, S04-F01, S05-F04, S07-F06, S12-F03 | Add protection at each named owner alongside or immediately after its behavioral work; do not reproduce lower-layer truth tables at the public facade. |
| 7 | Clarity, deterministic workflow, and test consolidation | S06-F01, S05-F05, S09-F05, S14-F06, S16-F01, S16-F02 | Remove writable non-policy state, delete or rewrite low-value tests while retaining stronger contracts, make transport tests environment-independent, and synchronize the maintained offline workflow. |
| 8 | Demonstrated performance work | S07-F04, S08-F06, S09-F04, S10-F05 | Optimize only after correctness and ownership changes settle each path. Preserve the counting, allocation, and behavior invariants specified by the findings and compare representative catalog, artifact, schema, and output sizes. |
The registry accounts for every canonical group exactly once: 27 behavioral
correctness groups in orders 1 through 3, two contract-consistency decisions,
two safe production refactors, 13 testing findings split by impact and
maintenance type, one clarity finding, and four measured efficiency findings.
### Dependency And Root-Cause Notes
- S05-F03 precedes S05-F04 and S08-F02 so expanded JSON-shape protection and
file-profile consumption do not institutionalize an unbounded shared copier.
- S17-F01 is the source-neutral owner for the S08-F01 and S11-F01 regressions;
their profile/config and invalid-request error mappings remain separate test
responsibilities.
- S07-F01, S07-F02, and S07-F03 should establish correct prompt-source
behavior before S07-F05 unifies its OS and `fs.FS` algorithms. S07-F04 then
removes unnecessary content reads from the unified selection path, while
S07-F06 protects the resulting semantic rule set.
- S08-F01 through S08-F05 establish profile validity and selection before
S08-F06 changes decoding work. Point-in-time lookup and overlay fallthrough
remain invariants; no engine-wide cache is implied.
- S10-F01 through S10-F04 establish exact JSON semantics, URL-safe schema
loading, compiled preparation, and cancellation before S10-F05 replaces
JSON-mode materialization. S10-F03 owns one read/compile plan per operation,
not cross-operation schema caching.
- S17-F02 normalizes request contracts before schema loading. S11-F02's public
preparation parity and invalid-request ordering remain the regression
boundary for that shared policy.
- S12-F01 and S12-F02 correct repair request and result semantics before
