Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cmd/gomodel/docs/swagger.json`:
- Around line 535-564: The Swagger path /p/{provider}/{endpoint} incorrectly
models multi-segment endpoints because OpenAPI 2.0 path params are
single-segment; update the `@Router` annotations in internal/server/handlers.go
(the lines containing "@Router /p/{provider}/{endpoint}" and the parameter docs
for "endpoint") to either document that endpoint must be URL-encoded when
containing slashes or change the route signature to capture the remainder via a
query or surrogate path (e.g., use a single catch-all encoded param or redesign
to /p/{provider} with a query param endpoint), then regenerate the OpenAPI
artifacts (run the doc generation that produces cmd/gomodel/docs/swagger.json
and cmd/gomodel/docs/docs.go) so the swagger.json reflects the corrected
parameter semantics.

In `@config/config_test.go`:
- Around line 29-30: Add tests to config/config_test.go that verify cascade
precedence for the new passthrough flags: ensure code defaults are overridden by
values in config.yaml (including variable expansion forms like ${VAR} and
${VAR:-default}) and that environment variables (ENABLE_PROVIDER_PASSTHROUGH and
NORMALIZE_PASSTHROUGH_V1_PREFIX) always win; specifically add cases that set
these keys in YAML (server.enable_provider_passthrough,
server.normalize_passthrough_v1_prefix), then override via os.Setenv before
calling Load(), and assert the resulting config matches the env value rather
than the YAML or default, and also add a test that YAML expansion works when
using ${VAR} and ${VAR:-default} for these keys.

In `@internal/auditlog/reader_mongodb.go`:
- Around line 236-240: The error label for findFirstByField is inconsistent:
findByResponseID passes "response id" while findByPreviousResponseID passes
"previous_response_id"; update one to match the other (pick a consistent format
like snake_case or human-readable) so both calls use the same label style—e.g.,
change the argument in findByResponseID or findByPreviousResponseID to the
chosen format when calling r.findFirstByField to ensure uniform error messages
across functions.

In `@internal/core/batch_json_test.go`:
- Around line 28-55: The test currently only asserts that x_top and x_item_flag
are objects, which allows empty objects to pass and misses regressions; update
the assertions to verify specific nested payload contents both on the original
req and after roundTrip JSON marshal/unmarshal: check concrete fields/values
inside req.ExtraFields["x_top"] and req.Requests[0].ExtraFields["x_item_flag"]
(e.g., expected keys/values) before calling json.Marshal, then after
unmarshalling verify decoded["x_top"] and first["x_item_flag"] contain the same
expected nested keys and values (use req, req.ExtraFields, req.Requests,
json.Marshal, json.Unmarshal, decoded, requests, first to locate the spots).

In `@internal/core/batch_semantic.go`:
- Around line 28-60: Add proper Go doc comments for the exported accessors
ChatRequest, ResponsesRequest, EmbeddingRequest, and ModelSelector on
DecodedBatchItemRequest: each comment should start with the method name (e.g.,
"ChatRequest ..."), briefly describe what it returns and the nil-receiver
behavior (ChatRequest/ResponsesRequest/EmbeddingRequest return nil if the
receiver is nil or if the underlying Request is not that type; ModelSelector
returns the selected model/provider or an error if the decoded request is nil or
unsupported), and mention any important error conditions for ModelSelector;
ensure comments follow Go doc conventions and are placed immediately above each
method.

In `@internal/core/chat_json.go`:
- Around line 5-83: Add a unit test that directly exercises ChatRequest's
UnmarshalJSON and MarshalJSON round-trip: write a new internal/core test (e.g.,
chat_json_test.go) that constructs JSON containing known fields (model,
messages, etc.) plus unknown top-level keys and unknown nested keys inside
objects in tools/messages, then call json.Unmarshal into a ChatRequest (invoking
ChatRequest.UnmarshalJSON) and assert those unknown keys are present in
r.ExtraFields, and finally json.Marshal the ChatRequest (invoking MarshalJSON)
and assert the serialized bytes still contain the unknown keys (verifying
marshalWithUnknownJSONFields round-trips the ExtraFields). Ensure the test
references ChatRequest, UnmarshalJSON, MarshalJSON, ExtraFields,
extractUnknownJSONFields and marshalWithUnknownJSONFields to validate the
contract.

In `@internal/core/embeddings_json.go`:
- Around line 5-53: Add a unit test that verifies EmbeddingRequest's custom
UnmarshalJSON/MarshalJSON round-trip preserves unknown top-level fields in
ExtraFields: create an EmbeddingRequest JSON blob containing known fields
(model, provider, input, encoding_format, dimensions) plus one or more unknown
fields, unmarshal it into EmbeddingRequest (testing UnmarshalJSON), assert known
fields are populated and ExtraFields contains the unknown keys, then marshal it
back (testing MarshalJSON via marshalWithUnknownJSONFields) and assert the
resulting JSON still contains the unknown fields with their values; reference
EmbeddingRequest, UnmarshalJSON, MarshalJSON, ExtraFields,
extractUnknownJSONFields, and marshalWithUnknownJSONFields when locating code to
test.

In `@internal/core/endpoints_test.go`:
- Around line 5-39: Add a negative test for discovery routes in
TestDescribeEndpointPath: call DescribeEndpointPath("/v1/models") and assert
that the returned struct has ModelInteraction == false (and optionally verify
Dialect/Operation/IngressManaged/BodyMode as appropriate for discovery routes);
update the tests table or add a separate t.Run case inside
TestDescribeEndpointPath that checks DescribeEndpointPath("/v1/models") does not
mark the path as a model interaction.

In `@internal/core/endpoints.go`:
- Around line 24-25: DescribeEndpointPath currently sets
EndpointDescriptor.BodyMode without the HTTP method, causing bodyless GET/DELETE
routes under /v1/batches* and /v1/files* to be misclassified; update the
classifier so it either accepts an additional parameter (HTTP method) or returns
a descriptor without BodyMode and provide a helper to derive BodyMode after the
action is known. Specifically, modify the DescribeEndpointPath signature or
behavior to include the request method (or omit BodyMode) and update any call
sites that use DescribeEndpointPath/EndpointDescriptor to compute BodyMode later
based on method+path (references: DescribeEndpointPath, EndpointDescriptor,
BodyMode).

In `@internal/core/files.go`:
- Around line 60-77: Add a proper Go doc comment for the exported function
EnrichFileCreateRequestSemantic describing what the function does (enriches a
FileRequestSemantic from multipart metadata), its parameters (req
*FileRequestSemantic, reader FileMultipartMetadataReader), the conditions under
which it returns req unchanged (nil req, wrong Action, or nil reader), and what
fields it populates (Provider, Purpose, Filename) before returning the enriched
*FileRequestSemantic; place the comment directly above the
EnrichFileCreateRequestSemantic function declaration following Go doc comment
conventions.

In `@internal/core/ingress.go`:
- Around line 6-17: Add brief doc comments to the IngressFrame struct fields to
clarify purpose and usage: annotate Method, Path, RouteParams, QueryParams,
Headers, ContentType to state what they represent; explain RawBody (contains the
request body bytes when within size limits) versus RawBodyTooLarge (flag set
when body exceeded capture limit and RawBody is truncated/empty); document
RequestID usage and TraceMetadata (map of tracing-related key/value pairs such
as trace/span ids or sampling metadata). Update the IngressFrame definition to
include those field comments so future maintainers understand intent and edge
cases.

In `@internal/core/message_json.go`:
- Around line 119-186: Add Go doc comments for the exported JSON methods to
match project conventions: add a comment starting with "ToolCall.UnmarshalJSON"
immediately above the ToolCall.UnmarshalJSON method describing that it
unmarshals a ToolCall from JSON and preserves unknown fields into ExtraFields,
add "ToolCall.MarshalJSON" above ToolCall.MarshalJSON explaining it marshals a
ToolCall to JSON including ExtraFields, and likewise add
"FunctionCall.UnmarshalJSON" and "FunctionCall.MarshalJSON" comments above their
respective methods indicating they unmarshal/marshal FunctionCall and
preserve/emit ExtraFields; keep the comments short, start with the exact method
names, and follow Go doc style.

In `@internal/core/responses_json.go`:
- Around line 171-185: The current call to extractUnknownJSONFields uses a
global exclusion list shared by all ResponsesInputElement variants and thus
drops fields that are unknown for the active variant but known for other
variants; change the code to compute the exclusion slice based on e.Type (the
active variant) before calling extractUnknownJSONFields so only the keys
actually consumed by that variant are excluded. Locate the unmarshalling logic
that sets e.ExtraFields (where extractUnknownJSONFields is called) and replace
the fixed list with a small switch/if on e.Type that builds the appropriate
[]string of known keys for each variant (include "type" plus the
variant-specific keys such as "id","role","status","content" for message-like
variants, and "call_id","name","arguments","output" for call-like variants),
then pass that computed slice to extractUnknownJSONFields and assign the
returned map to e.ExtraFields.

In `@internal/core/responses.go`:
- Around line 5-24: Update the Go doc comments on the exported types
ResponsesRequest and ResponsesInputElement to document the ExtraFields contract:
state that any unknown JSON members encountered during unmarshaling are
preserved in ExtraFields (map[string]json.RawMessage) and will be included when
marshaling so callers can rely on round-tripping of unknown fields; mention that
ExtraFields is ignored by Swagger (swaggerignore) and that consumers should
prefer typed fields when present but can read/write ExtraFields for extensions.
Ensure the new text appears immediately above the type definitions for
ResponsesRequest and ResponsesInputElement.

In `@internal/core/semantic_canonical.go`:
- Around line 198-211: Add a Go doc comment above the exported function
DecodeCanonicalSelector that briefly describes its purpose, parameters and
return values; mention that it decodes a canonical request from body using the
codec resolved by canonicalOperationCodecFor on the provided *SemanticEnvelope
(env), and returns the model and provider strings along with an ok boolean
(false on nil env, codec lookup failure, or decode error), and reference
semanticSelectorFromCanonicalRequest as the final step of the operation.

In `@internal/guardrails/provider.go`:
- Around line 206-267: The code in patchChatMessagesJSON consumes
systemOriginals from the front, causing prepended system messages to inherit the
wrong original envelope; update the algorithm to match existing system messages
from the tail (i.e., consume systemOriginals from the end when aligning with
modified system messages) before treating remaining system entries as
insertions, and apply the same tail-based logic to the other remapping loop
referenced (the similar implementation at lines ~505-558) so both use the same
stable tail-match strategy; ensure you still call patchRawChatMessage for
matched originals and json.Marshal for truly new system messages, and update the
nextSystem/indices handling accordingly.

In `@internal/llmclient/client_test.go`:
- Around line 400-486: The DoPassthrough retry behavior currently applies to all
methods; change DoPassthrough to only perform retries for explicit replay-safe
methods or when the caller opts in: check the Request.Method inside
DoPassthrough (the function named DoPassthrough and its call to c.isRetryable())
and if Method is not a replay-safe method (e.g., only allow GET and HEAD) then
bypass the retry logic and return the single upstream response, or alternatively
require an explicit Request flag (e.g., AllowRetries) to enable retries for
unsafe methods; update the branch that calls c.isRetryable() to first validate
Request.Method (or the opt-in flag) so non-idempotent methods are never
automatically retried.

In `@internal/llmclient/client.go`:
- Around line 193-204: The circuit-breaker half-open probe can remain unresolved
when a probe request returns a non-retryable, non-5xx status (e.g. 400/401/404)
because DoRaw/DoStream return without calling RecordSuccess/RecordFailure;
update the shared completion path so that any admitted half-open probe (acquired
via c.circuitBreaker.acquire and stored in scope.halfOpenProbe) is always
resolved: call c.circuitBreaker.RecordSuccess(probe) for non-retryable completed
responses (the same outcome DoPassthrough treats as success) and call
RecordFailure for retryable/5xx errors, ensuring finishRequest still runs (use
requestScope / scope handling in the completion logic used around DoRaw,
DoStream, and DoPassthrough to invoke RecordSuccess/RecordFailure
appropriately).
- Around line 401-459: DoPassthrough currently retries every request body which
can cause duplicate provider-side effects for non-idempotent methods; update
DoPassthrough to only perform the retry loop when the request is safe to replay
by checking request idempotency up-front (e.g., allow retries when
Request.Method is one of idempotent methods like GET/HEAD/PUT/OPTIONS or when an
explicit idempotency key header is present such as "Idempotency-Key"); gate the
retry behavior before entering the for loop that uses maxAttempts/waitForRetry
and before calling isRetryable/doHTTPRequest, and ensure non-idempotent methods
immediately return the first response/error (or set maxAttempts=1) so functions
and symbols to change include DoPassthrough, the for attempt loop using
maxAttempts, waitForRetry, isRetryable, and the check for req.Headers
(idempotency key) or req.Method.

In `@internal/providers/anthropic/anthropic.go`:
- Around line 163-167: Update the PassthroughResponse type comment to document
the ownership contract: state that the Body field is an io.ReadCloser and that
callers are responsible for closing it when finished (i.e., the provider returns
a PassthroughResponse with Body set, and the receiver must call Close on that
ReadCloser). Add this note to the comment above the core.PassthroughResponse
struct in internal/core/passthrough.go so all providers (and callers like
handlers) see the requirement.

In `@internal/providers/file_adapter_openai_compat.go`:
- Around line 17-52: Add regression tests for validatedOpenAICompatibleFileID
and doOpenAICompatibleFileIDRequest in a *_test.go: verify that whitespace-only
IDs return an invalid-request error, that IDs with surrounding whitespace are
trimmed before being sent (use a fake llmclient.Client to assert the Endpoint
contains the trimmed id), that response objects returned by
doOpenAICompatibleFileIDRequest carry the normalized (trimmed) ID, and that when
upstream responses have an empty Object field the function synthesizes
defaultObject (test both core.FileObject and core.FileDeleteResponse branches).
Use table-driven tests and a mock client to simulate upstream responses and
errors.

In `@internal/providers/openai/openai.go`:
- Around line 101-129: adaptForOSeries currently swallows
json.Marshal/json.Unmarshal failures and returns lossy payloads; change it to
return an error when (un)marshalling fails so the caller can abort: update
adaptForOSeries signature to return (any, error), keep the successful path that
unmarshals into var raw map[string]json.RawMessage, map "max_tokens" ->
"max_completion_tokens" and delete "temperature", but on json.Marshal or
json.Unmarshal errors return core.GatewayError with Category set to
core.InvalidRequestError (include the underlying error message), rather than
returning a partial map or the original req so opaque fields are not dropped
silently; update callers to handle the (any, error) result accordingly.

In `@internal/providers/responses_adapter.go`:
- Around line 547-579: The map[string]string branch in
normalizeResponsesImageURLForChat returns an ImageURLContent but drops unknown
keys instead of populating ExtraFields; update that branch to capture extra
fields the same way as the map[string]interface{} branch by converting the
string map into a form rawJSONMapFromUnknownKeys can use (or by building
ExtraFields from keys other than "url","detail","media_type") and set
ExtraFields on the returned core.ImageURLContent; apply the same change to the
analogous function handling audio URLs (the corresponding branch around lines
582-605) so both map[string]string and map[string]interface{} paths preserve
nested/unknown keys via rawJSONMapFromUnknownKeys.

In `@internal/providers/router_test.go`:
- Around line 737-769: Add unit tests covering passthrough error cases: (1)
Unknown provider — call router.Passthrough with a provider name not registered
in newMockLookup and assert an error is returned and that it can be cast to
*core.GatewayError (use errors.As); (2) Provider error propagation — register a
mockProvider that returns an error from its Passthrough implementation, invoke
router.Passthrough and assert that the same/provider error is propagated; (3)
Empty registry — construct router via NewRouter(newMockLookup() without any
models) and call router.Passthrough to assert errors.Is(err,
ErrRegistryNotInitialized). Reference router.Passthrough, NewRouter,
newMockLookup, mockProvider, ErrRegistryNotInitialized and core.GatewayError
when locating/creating these tests.

In `@internal/providers/router.go`:
- Around line 60-71: resolveProviderType currently uses providerByType (which
only returns providers that own discovered models) causing provider-typed routes
to fail when a provider has no models; change resolveProviderType to look up
providers from a dedicated provider-type registry instead of providerByType
(e.g., use or add a map/lookup like r.providerRegistry or r.providersByType and
a getter method such as r.providerByTypeRegistry/FindProviderByType) and update
resolveProviderType to call that registry lookup; ensure the registry is
initialized before routing checks (keep the existing checkReady call) so
provider-typed routes work even when /models sync yields zero models.

In `@internal/server/handlers.go`:
- Around line 371-382: The handler currently fully buffers uploads via
requestBodyBytes and PassthroughRequest.Body, which risks OOM; change to stream
the request instead of reading into memory by updating core.PassthroughRequest
to accept an io.ReadCloser or io.Reader (e.g., Body io.ReadCloser), update
passthroughProvider.Passthrough to take that streamed Body, and in handlers.go
pass c.Request().Body (or an io.LimitedReader wrapping it to enforce a hard size
cap) instead of calling requestBodyBytes; also adjust downstream implementations
(providers and any callers of Passthrough) to read/close the stream and to
respect the optional size limit.
- Around line 224-262: The passthrough header logic in
buildPassthroughHeaders/skipPassthroughHeader/copyPassthroughResponseHeaders
leaks sensitive request and response metadata (Cookie, Forwarded, X-Forwarded-*,
and Set-Cookie) and ignores hop-by-hop headers named in the Connection header;
update these functions by splitting request vs response handling so request-side
filter explicitly excludes "Cookie", "Forwarded", and any "X-Forwarded-*"
headers, and response-side filter blocks "Set-Cookie" and any headers listed in
the incoming Connection header; also modify skipPassthroughHeader to treat those
names as skipped and ensure copyPassthroughResponseHeaders consults the
Connection header values and uses
http.CanonicalHeaderKey(strings.TrimSpace(...)) for comparisons while preserving
existing sensitive-header redaction behavior in audit logs (do not log header
values).
- Around line 291-329: The Swagger annotations for the passthrough handler are
incorrect: update the API docs for the passthrough endpoints (references:
proxyPassthroughResponse, ProviderPassthrough handler and
passthroughStreamAuditPath usages) to declare the path parameter as a
catch-all/wildcard (not a single-segment param) and mark responses as opaque
passthrough (allow arbitrary status codes and content-types, e.g., binary/any
and SSE/stream) rather than a single JSON schema; then regenerate docs by
running make swagger so generated clients reflect the actual runtime behavior.

In `@internal/server/http_test.go`:
- Around line 523-547: Update the TestProviderPassthroughRoute_EnabledByDefault
test to also exercise the normalized v1 prefix: send an additional httptest
request to "/p/openai/v1/responses" (same body and headers) and assert
srv.ServeHTTP returns http.StatusOK and that mock.lastPassthroughProvider ==
"openai"; this ensures the NormalizePassthroughV1Prefix behavior is covered
alongside the existing "/p/openai/responses" path and prevents routing
regressions.
- Around line 549-565: Update
TestProviderPassthroughRoute_DisabledRequiresAuthBefore404 to also assert
behavior when authenticated: create a second httptest request to
"/p/openai/responses" with the same JSON body but include the correct MasterKey
header (matching Config.MasterKey), call srv.ServeHTTP on a new recorder, assert
the response status is http.StatusNotFound (404), and verify your mockProvider
passthrough handler (mockProvider) was NOT invoked (e.g., check a called flag or
counter on mockProvider) to confirm DisableProviderPassthrough prevents routing
even for authenticated requests.

In `@internal/server/http.go`:
- Around line 45-46: Rename the confusing flag
DisablePassthroughV1PrefixNormalization to a positively named
EnablePassthroughV1PrefixNormalization and invert its semantics (true =>
normalization enabled) throughout the codebase: update the struct field name,
all references/usages, any config parsing or defaults that set/expect the old
flag, and tests; where code currently checks
DisablePassthroughV1PrefixNormalization (e.g., conditional branches that skip
normalization), flip the condition to use EnablePassthroughV1PrefixNormalization
and invert the boolean logic so behavior is preserved but the flag reads
positively. Ensure documentation/comments and any environment/config keys are
updated to match the new name and semantics.

In `@internal/server/ingress_test.go`:
- Around line 29-75: Add a test that exercises IngressCapture when the
X-Request-ID header is absent: create a request without setting "X-Request-ID",
run it through the same IngressCapture middleware (use the existing pattern with
capturedFrame := core.GetIngressFrame(c.Request().Context()) inside the
handler), then assert that capturedFrame.RequestID is non-empty and is a valid
UUID (e.g., parse it with a UUID parser or assert it matches UUID format). Keep
the rest of the checks minimal (ensure downstream body still equals the original
body) and place this as a new test case or an additional test function alongside
TestIngressCapture_SetsFrameAndSemanticEnvelope.

In `@internal/server/ingress.go`:
- Around line 88-99: The helper extractTraceMetadata drops additional header
lines by only using values[0]; change it to preserve all header values by
joining the values slice (preserving order) into a single string (e.g.
strings.Join(values, ",")) and use that joined string for the TrimSpace and
assignment to metadata[key]; keep the existing keys slice (traceHeaders) and
return behavior unchanged so callers of extractTraceMetadata get the full
combined header value for Tracestate/Baggage/Traceparent.
- Around line 32-43: IngressFrame.RequestID is being populated only from
req.Header but the canonical ID lives in req.Context(); change the logic that
constructs core.IngressFrame (where RequestID is set) to first attempt to read
the request ID from req.Context(), then fall back to
req.Header.Get("X-Request-ID"), and if still empty generate a new UUID (v4) and
store it back into the request context (and set the X-Request-ID header) so
subsequent providers and audits see the same canonical ID; update any helper
that extracts/injects the request ID into context (or add one) and ensure you
use that context-derived value for IngressFrame.RequestID.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cmd/gomodel/docs/swagger.json`:
- Around line 535-976: The passthrough OpenAPI responses for the
/p/{provider}/{endpoint} operations are too narrow (all methods return 200 +
type:file), causing generated clients to mishandle valid upstream responses;
update the Swagger annotations in the passthrough handler (look for the handler
that registers /p/{provider}/{endpoint} in your *handler*.go) so each HTTP
method advertises method-appropriate success responses (e.g., POST/PUT: allow
200/201/202; DELETE/OPTIONS/HEAD: include 204 where appropriate; HEAD: do not
declare a response body schema) or declare a generic opaque response that
permits multiple success status codes, then regenerate the Swagger artifacts by
running the documented make swagger step.

In `@config/config_test.go`:
- Around line 271-304: Replace manual os.Setenv/_ = os.Unsetenv usage in the
subtests with t.Setenv to ensure automatic cleanup and consistency with other
tests; in the loop body that uses withTempDir and calls Load(), call
clearAllConfigEnvVars(t) at the start of each subtest to ensure isolation, and
remove the outer clearAllConfigEnvVars(t) invocation so cleanup is per-subtest.
Specifically update the subtest that writes config.yaml and sets
ENABLE_PROVIDER_PASSTHROUGH and NORMALIZE_PASSTHROUGH_V1_PREFIX to use
t.Setenv("ENABLE_PROVIDER_PASSTHROUGH", tt.envEnabled) and
t.Setenv("NORMALIZE_PASSTHROUGH_V1_PREFIX", tt.envNormalize) and add
clearAllConfigEnvVars(t) before those t.Setenv calls; leave the rest of the
assertions against Load(), result.Config.Server.EnableProviderPassthrough and
result.Config.Server.NormalizePassthroughV1Prefix unchanged.
- Around line 310-314: Replace the manual os.Setenv and manual cleanup in the
withTempDir test helper with t.Setenv to ensure consistent test environment
handling; specifically, in the closure passed to withTempDir where
PASSTHROUGH_ENABLED_FROM_YAML is set, call
t.Setenv("PASSTHROUGH_ENABLED_FROM_YAML", "false") instead of os.Setenv and
remove the t.Cleanup Unsetenv logic so the test framework will restore the env
automatically.

In `@internal/core/batch_semantic.go`:
- Around line 155-166: Replace the manual loop that checks whether operation
exists in operations with the standard library helper slices.Contains to
simplify the code: import "slices" and change the logic around variables
operations and operation so it becomes if len(operations) > 0 &&
!slices.Contains(operations, operation) { return nil, false, nil }, preserving
the exact behavior and return values.

In `@internal/core/ingress.go`:
- Around line 3-31: The struct IngressFrame is documented as immutable but
exposes mutable exported fields (e.g., RawBody, RouteParams, QueryParams,
Headers, TraceMetadata) that callers can modify; either make the fields
unexported and add accessor methods that return defensive copies (e.g., methods
RawBody() []byte, RouteParams() map[string]string, QueryParams()
map[string][]string, Headers() map[string][]string, TraceMetadata()
map[string]string) to guarantee immutability, or change the type comment to
remove the immutability claim—pick one approach and apply consistently to the
IngressFrame definition and any code constructing it (constructors should
populate unexported fields and callers must use accessors).

In `@internal/core/message_json.go`:
- Around line 19-27: Update the Go doc comments for the exported JSON methods
(e.g., Message.UnmarshalJSON, Message.MarshalJSON and any other exported
Marshal/UnmarshalJSON methods in this file) to state that unknown JSON members
are preserved in the ExtraFields map (type ExtraFields /
map[string]json.RawMessage) and that these methods continue to perform content
validation and null handling; apply the same doc update to the other exported
JSON-method comments indicated (the blocks at the other ranges) so the public
docs reflect preservation of unknown fields.

In `@internal/core/passthrough.go`:
- Around line 9-13: The PassthroughRequest struct's Headers field currently
flattens repeated headers as map[string]string; change Headers to preserve
repeated values by using map[string][]string (or http.Header) on the request
side (PassthroughRequest.Headers) and update all codepaths that construct, read,
or forward PassthroughRequest (e.g., any function that creates a
PassthroughRequest, the passthrough handler that reads Headers, and any
forwarding logic that copies headers to an http.Request) to use the new
slice-based type and to avoid collapsing or joining header values; ensure
callers convert from existing representations explicitly (joining/splitting only
when necessary) and run tests to update any assertions expecting single-string
header values.

In `@internal/guardrails/provider.go`:
- Around line 581-589: The code in applyGuardedMessageToOriginal preserves the
original's tool metadata via cloneChatMessageEnvelope but only overwrites it
when modified.ToolCalls or modified.ToolCallID are non-empty, so
guardrail-driven removals are ignored; change applyGuardedMessageToOriginal to
always assign the guarded values (set preserved.ToolCalls =
cloneToolCalls(modified.ToolCalls) even when empty and set preserved.ToolCallID
= modified.ToolCallID unconditionally) so empty/cleared tool_calls or
tool_call_id from the guarded Message replace the originals (use cloneToolCalls
and mirror the behavior of patchRawChatMessage).

In `@internal/providers/file_adapter_openai_compat.go`:
- Around line 18-19: Replace the incorrect use of core.NewInvalidRequestError in
the client == nil check inside internal/providers/file_adapter_openai_compat.go:
instead of returning core.NewInvalidRequestError("provider client is not
configured", nil) when the provider client is missing, return a gateway-level
error using the core.NewGatewayError constructor with the provider_error
category (e.g., the GatewayError provider_error constant) and the same
descriptive message, preserving the nil/underlying error field; update the
return to use core.NewGatewayError(..., "provider client is not configured",
nil) so the error is classified as a provider/server-side GatewayError rather
than an invalid_request_error.
- Around line 146-151: Update the exported Go doc comments for
GetOpenAICompatibleFile, DeleteOpenAICompatibleFile and
GetOpenAICompatibleFileContent to state that incoming IDs are normalized via
validatedOpenAICompatibleFileID (IDs are trimmed/normalized before the request)
and that the returned response objects have synthesized/normalized ID and Object
fields added when missing; mention the exact functions (GetOpenAICompatibleFile,
DeleteOpenAICompatibleFile, GetOpenAICompatibleFileContent) so readers know the
public contract includes ID normalization and response field synthesis.

In `@internal/providers/responses_adapter.go`:
- Around line 266-270: convertResponsesInputItems and mergeAssistantMessage
currently allow assistant messages to be merged while discarding ExtraFields;
change the logic to preserve metadata by preventing merges when either message
has non-nil/non-empty ExtraFields or implement an explicit merge policy for
ExtraFields. Specifically, update mergeAssistantMessage (or add a pre-check in
convertResponsesInputItems) to detect item.ExtraFields and other.ExtraFields
(use core.CloneRawJSONMap semantics if merging is chosen) and if either contains
data, do not combine content/tool calls — instead return separate messages or
merge ExtraFields explicitly according to a defined policy so top-level metadata
is not silently lost.

In `@internal/providers/router.go`:
- Around line 68-76: In resolveProviderType ensure that when r.checkReady()
returns ErrRegistryNotInitialized you return a typed *core.GatewayError (not the
raw error) so handleError() will serialize it; modify Router.resolveProviderType
to detect err == ErrRegistryNotInitialized and return a constructed
core.GatewayError (using the appropriate category, e.g., provider_error or
not_found_error, and the original error message) instead of returning the raw
err from checkReady(); reference resolveProviderType, checkReady,
ErrRegistryNotInitialized, core.GatewayError and handleError when making the
change.

In `@internal/server/handlers.go`:
- Around line 406-412: Replace the raw request context with a context wrapped by
core.WithRequestID before calling passthroughProvider.Passthrough so the
provider gets the propagated request-id; specifically, instead of ctx :=
c.Request().Context(), call core.WithRequestID(c.Request().Context(),
c.Request().Header.Get("X-Request-ID")) and pass that ctx into
passthroughProvider.Passthrough; also ensure buildPassthroughHeaders adds or
preserves the "X-Request-ID" header (using core.RequestIDFromContext(ctx) if the
incoming header was empty) so core.PassthroughRequest.Headers carries the
request id downstream.

---

Outside diff comments:
In `@internal/llmclient/client.go`:
- Around line 154-163: The DoRaw retry loop must be disabled when
Request.RawBodyReader is set because that reader is one-shot; update the retry
logic in the DoRaw function (and any other retry sites referenced around the
existing attempts at lines similar to 299-310 and 582-584) to detect if
req.RawBodyReader != nil and in that case avoid multiple attempts (e.g., set
maxAttempts=1 or skip the retry branch) so the request is only sent once; also
ensure the code treats RawBodyReader as mutually exclusive with Body/RawBody as
already documented in the Request struct to avoid ambiguous behavior.

In `@internal/server/http.go`:
- Around line 87-95: The metrics conflict check should also block any configured
metricsPath that targets passthrough routes under /p/ to avoid auth bypass:
update the guard that currently checks metricsPath against "/v1" and
strings.HasPrefix(metricsPath, "/v1/") to also check for metricsPath == "/p" or
strings.HasPrefix(metricsPath, "/p/"), log the same warning (include
cfg.MetricsEndpoint and normalized metricsPath) and set metricsPath = "/metrics"
before appending to authSkipPaths; make the identical change to the other
metrics-guard instance that uses the same variables (metricsPath,
cfg.MetricsEndpoint, authSkipPaths) in this file.

---

Duplicate comments:
In `@internal/core/chat_json_test.go`:
- Around line 72-83: The test currently only asserts presence of x_message_meta,
x_function_meta, and related extra-field objects; update the assertions in Test
(around req.Messages[0], req.Messages[0].ToolCalls, and
req.Messages[0].ToolCalls[0].Function) to validate specific nested keys/values
(e.g., expected fields inside ExtraFields["x_message_meta"],
ExtraFields["x_tool_call"], and Function.ExtraFields["x_function_meta"] and any
x_trace entries) both before and after json.Marshal/unmarshal, ensuring the
nested values equal the expected strings/structures instead of merely non-nil
objects so empty-object regressions are caught.

In `@internal/core/embeddings_json_test.go`:
- Around line 67-72: The test currently only asserts that decoded["x_trace"] is
an object; update the test to also assert the nested id field survives the
round-trip by casting decoded["x_trace"] to a map (e.g., xTraceMap :=
decoded["x_trace"].(map[string]any)) and then checking xTraceMap["id"] ==
<original expected id value> (or t.Fatalf on mismatch). Ensure you reference
decoded and the nested "id" key so the test fails if the object is empty but
missing its expected content.

In `@internal/guardrails/provider.go`:
- Around line 234-245: The current tail-only matching in
tailMatchedSystemOffsets misaligns system messages when messages are
appended/inserted/removed; replace the simplistic tail-based alignment with a
stable alignment step (e.g., compute an LCS or do combined leading+trailing
matching) between systemOriginals and the list of modified system messages
before you compute systemMatchStart/originalSystemStart so that subsequent logic
in the loop (references to systemMatchStart, originalSystemStart, nextSystem,
and patchRawChatMessage) maps preserved envelopes to the correct original system
messages; ensure the function tailMatchedSystemOffsets (or the call site that
uses it) returns indices based on that stable alignment so insertions/deletions
no longer cause envelope swaps.

In `@internal/providers/file_adapter_openai_compat_test.go`:
- Around line 20-57: The test must assert HTTP method and exercise the DoRaw
path used by GetOpenAICompatibleFileContent so normalization is fully covered:
update TestValidatedOpenAICompatibleFileID (or add a sibling test) to have the
test server verify r.Method for the JSON /files/{id} request (e.g., assert GET
or DELETE as appropriate in the handler), and add a case that calls
GetOpenAICompatibleFileContent with an id containing surrounding whitespace so
the handler for /files/{id}/content (the DoRaw path) asserts the request method
and returns the normalized id in the response body; then assert the returned id
equals the trimmed/normalized value and keep the existing GatewayError
assertions for invalid (whitespace-only) ids. Ensure you reference
validatedOpenAICompatibleFileID and GetOpenAICompatibleFileContent/DoRaw when
locating where to add these checks.

In `@internal/server/handlers.go`:
- Around line 224-236: The buildPassthroughHeaders function currently forwards
headers named in the incoming Connection header; parse the src "Connection"
header values, canonicalize each token (use http.CanonicalHeaderKey and
strings.TrimSpace) and treat those tokens as hop-by-hop names to skip just like
skipPassthroughRequestHeader does; update buildPassthroughHeaders (and the
similar logic around the other block that covers lines 259-279) to ignore any
header whose canonical name appears in the parsed Connection list so no
Connection-nominated headers (e.g. X-Debug) are copied into dst.

In `@internal/server/ingress_test.go`:
- Around line 112-143: The test TestIngressCapture_GeneratesRequestIDWhenMissing
should also assert that the generated RequestID is written back to the HTTP
header and stored in the request context so downstream code sees the same ID:
after calling handler(c) fetch the X-Request-ID header from
rec.Result().Header.Get("X-Request-ID") and assert it equals
capturedFrame.RequestID, and also retrieve the value from context via
core.GetRequestID(c.Request().Context()) or the equivalent context accessor used
by core.WithRequestID(...) and assert that equals capturedFrame.RequestID;
ensure you reference the existing middleware IngressCapture, capturedFrame from
core.GetIngressFrame, and the X-Request-ID header in these new assertions.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@config/config_test.go`:
- Around line 301-325: The test TestLoad_PassthroughFlags_YAMLExpansion is
nondeterministic because it relies on ${PASSTHROUGH_NORMALIZE_FROM_YAML:-false}
but never ensures PASSTHROUGH_NORMALIZE_FROM_YAML is unset; make the
YAML-expansion hermetic by explicitly unsetting that env var before writing the
YAML (e.g. call os.Unsetenv("PASSTHROUGH_NORMALIZE_FROM_YAML") or ensure
clearAllConfigEnvVars(t) clears that specific name) so the default branch is
exercised reliably when Load() is called.

In `@internal/llmclient/client_test.go`:
- Around line 436-606: Update the passthrough tests to assert replay-safety
semantics more tightly: in
TestClient_DoPassthrough_RetriesWhenIdempotencyKeyPresent, modify the test
server handler (the httptest handler inside that function) to validate that the
incoming request contains the "Idempotency-Key" header and fail the test if it's
missing (this proves the key is forwarded upstream); add a new test (e.g.,
TestClient_DoPassthrough_NonReplayableRawBody_DoesNotRetry) that supplies a
non-replayable RawBody reader (a reader that errors on a second read or is a
one-shot pipe) in the Request passed to Client.DoPassthrough and asserts the
server saw only one attempt and the client did not retry, referencing
Request.RawBody and DoPassthrough to locate where to construct the one-shot
reader and check retry behavior.

In `@internal/providers/anthropic/anthropic_test.go`:
- Around line 3988-4047: The passthrough test needs to assert X-Request-ID
generation/propagation: update TestPassthrough to capture the incoming
"X-Request-ID" header from the test server (add a gotRequestID variable in the
httptest handler) and remove any X-Request-ID from the request Headers in
core.PassthroughRequest so the provider must generate it; after calling
provider.Passthrough verify gotRequestID is non-empty and a valid UUID (or at
least matches UUID format), and also add an additional subcase where you set a
known X-Request-ID in the request headers and assert the same value is forwarded
(to cover both generation and propagation paths). Ensure you modify only
TestPassthrough and its request headers; use NewWithHTTPClient,
provider.Passthrough, and core.PassthroughRequest to locate the code to change.

In `@internal/providers/file_adapter_openai_compat_test.go`:
- Around line 184-239: Add a regression sub-test to
TestGetOpenAICompatibleFileContent that simulates a non-2xx response from the
content endpoint (e.g., have the httptest server return a 500 status and
optional error body) for a valid trimmed id, call
GetOpenAICompatibleFileContent(ctx, client, id), and assert it returns an error
that matches errors.As(err, &core.GatewayError) and verifies the GatewayError
Type/fields as the other adapter tests do; reference
GetOpenAICompatibleFileContent and the existing test scaffold (httptest server,
newOpenAICompatibleTestClient) to add the 4xx/5xx case alongside the existing
success and input-validation cases.

In `@internal/providers/responses_adapter.go`:
- Around line 251-256: The typed `function_call_output` branch returns
item.Output as-is which causes structured typed outputs to be sent as JSON
objects instead of the expected string; update the code that builds the
core.Message (the return that sets Role "tool" and ToolCallID callID) to
JSON-stringify item.Output the same way the map[string]interface{} branch does
(i.e., serialize item.Output to a string and use that string for Content),
preserving ExtraFields via core.CloneRawJSONMap(item.ExtraFields).

In `@internal/server/handlers_test.go`:
- Around line 2015-2023: The test's JSON payload (reqBody) hard-codes
"provider":"openai", causing a false positive for the selector-extraction
behavior; remove the explicit "provider" key from the batch item body in the
selector-extraction test (and the similar cases around the other occurrences) so
the handler must derive provider from the URL, or alternatively update the test
assertion to check the provider value produced by URL normalization/captured
batch state instead of the hard-coded field; update the test expectations in the
same test function that constructs reqBody and any assertions that currently
rely on the hard-coded provider.
- Around line 3045-3279: Add two assertions/tests: (1) in the passthrough
happy-path (e.g., TestProviderPassthrough_OpenAI or a new
TestProviderPassthrough_AutoGeneratesRequestID) ensure when the incoming request
lacks X-Request-ID the handler generates one and that
provider.lastPassthroughReq.Headers.Get("X-Request-ID") is non-empty (and
optionally UUID-format) and that the response includes the same X-Request-ID
header; (2) add a failing-upstream test (or extend
TestProviderPassthrough_RejectsUnsupportedProvider) that triggers a 4xx/upstream
error from mockProvider and assert the HTTP response body is the typed JSON
error produced by handleError() (i.e., contains structured fields like
code/message) and that errors.As(GatewayError) path is exercised by verifying
the response Content-Type is application/json and X-Request-ID is present; focus
changes around handler.ProviderPassthrough, handleError, GatewayError usage and
mockProvider.passthroughResponse to simulate the error.

In `@internal/server/handlers.go`:
- Around line 179-186: The function isSupportedPassthroughProvider currently
hardcodes "openai" and "anthropic" which prevents extending passthrough
providers; update it to consult a configurable source (e.g., a slice/set in a
config struct or an environment-backed map) instead of the switch, initialize
that list during startup (e.g., in your config loader) and change
isSupportedPassthroughProvider to trim and check membership against that
runtime-configured list; ensure the symbol names involved are the existing
isSupportedPassthroughProvider function and the app configuration (e.g.,
Config.SupportedPassthroughProviders or a package-level
supportedPassthroughProviders variable) so future providers can be added without
code changes.

---

Duplicate comments:
In `@cmd/gomodel/docs/swagger.json`:
- Around line 586-590: Update the Swagger annotations in the handler source
(files matching *handler*.go) for the /p/{provider}/{endpoint} path and the
other listed occurrences (around the noted blocks) to remove any "schema" or
"type" entries for HEAD success responses and 204 No Content responses (i.e., do
not declare a response body for HEAD or 204), then regenerate the OpenAPI JSON
by running the project's swagger generation (e.g., make swagger) so
cmd/gomodel/docs/swagger.json no longer advertises impossible payloads; look for
and edit the response annotations in the relevant handler functions that
document the path/method success responses and remove the body schema lines
before regenerating.

In `@internal/core/ingress.go`:
- Around line 3-32: IngressFrame currently exposes mutable fields (RawBody,
RouteParams, QueryParams, Headers, TraceMetadata) so callers can mutate the
captured frame; change IngressFrame to keep those fields unexported (e.g.,
rawBody []byte, routeParams map[string]string, queryParams map[string][]string,
headers map[string][]string, traceMetadata map[string]string) and add a
constructor like NewIngressFrame(...) that defensively copies incoming
maps/slices/bytes into the private fields; expose only accessor methods
GetRawBody(), GetRouteParams(), GetQueryParams(), GetHeaders(),
GetTraceMetadata() that return deep copies (or read-only views) so consumers
cannot mutate the internal state, while keeping other exported fields (Method,
Path, ContentType, RawBodyTooLarge, RequestID) as needed.