Skip to content

Commit c58e0d6

Browse files
authored
docs(devlog): open the cross-path contract unit for the next release (#5371)
1 parent a499746 commit c58e0d6

1 file changed

Lines changed: 113 additions & 0 deletions

File tree

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Cross-path contract gaps before the next release
2+
3+
Status: open. Target branch for every lane: `dev`.
4+
5+
The batch that landed on 2026-09-20 fixed several defects one path at a time. The
6+
audit that followed found the same shape repeating: a policy is correct where it
7+
was written and absent one wrapper away, or a guard that protects a real hazard
8+
also refuses the supported case. This unit closes that class before the release
9+
rather than adding features.
10+
11+
Each lane is one branch, ordered commits, and one pull request to `dev`. No
12+
stacked child pull requests, no native stacks. A lane owns its files; where two
13+
lanes touch the same subsystem the split is written below so the merge is a union
14+
and not a conflict.
15+
16+
## L1 — one replay refusal on all three HTTP surfaces
17+
18+
`src/lib/upstream-retry.ts` answers an ambiguous connection loss with
19+
`upstream_reset_replay_refused` and no `Retry-After`, which means "this may
20+
already have executed, do not send it again". `src/server/chat-native.ts` and
21+
`src/server/responses/passthrough-error.ts` recognise that. The translated Chat
22+
wrapper in `src/server/chat-completions.ts` does not: it preserves only the cyber
23+
policy code and `model_not_found`, assigns `upstreamCode` just when
24+
`classifyError` produced no code, and then adds a default `Retry-After: 2`. A
25+
refusal to replay leaves the proxy as an ordinary rate limit that clients retry.
26+
27+
Carry the replay verdict as a property of the result the three wrappers share, so
28+
no wrapper re-derives it from a status code. Then decide the status deliberately:
29+
the widely used Python SDK retries 429 by default, so preserving the code while
30+
dropping `Retry-After` does not by itself stop a resend. The acceptance evidence
31+
is the number of physical upstream sends observed through a client with retries
32+
enabled, not a single `fetch`.
33+
34+
## L2 — the Chat translation inbound loses developer position
35+
36+
Outbound keeps a `developer` message where the conversation put it
37+
(`src/adapters/openai-chat/messages.ts`). Inbound does not:
38+
`src/chat/inbound.ts` routes both `system` and `developer` into
39+
`systemParts` and joins them into `body.instructions`, so
40+
`U1 → A1 → D2 → U2` becomes `instructions: D2` with `U1 → A1 → U2`. Position
41+
is gone before any adapter sees it, and no outbound fix can restore it.
42+
43+
This is not a rare internal path. Combo, policy, synthetic effort rows and several
44+
preprocessing routes translate, so the same transcript behaves differently once a
45+
routing feature is on. The Claude inbound already models this correctly by keeping
46+
a mid-conversation instruction as a developer input item
47+
(`src/claude/inbound.ts`, `src/responses/parser.ts`). Reuse that representation
48+
for the mid-conversation case only; a leading system block keeps its current
49+
treatment.
50+
51+
## L3 — an explicit developer-role setting is ignored natively
52+
53+
`foldDeveloperRoleToSystem` decides the role on the translated path. The native
54+
Chat passthrough (`src/adapters/openai-chat/passthrough.ts`) forwards the
55+
caller's `messages` untouched and never reads it, so an operator who recorded
56+
"this destination rejects `developer`" still sends `developer` there. Honour the
57+
explicit setting on both paths and leave the unset default alone: the existing
58+
native test that preserves caller messages stays green.
59+
60+
## L4 — the paginated-history transition, past "enable succeeded"
61+
62+
The provider-table transition on a paginated `openai` home now completes. The
63+
remaining risk is the state after it. Acceptance is destination preservation, not
64+
a successful sync: existing conversations must not resume against the default
65+
OpenAI endpoint, new conversations must use the injected provider and catalog,
66+
restore must return operator-owned settings and remove only what this project
67+
owns, a user-owned root override must not be taken over, and an admission-token
68+
home must still be refused rather than reported as supported.
69+
70+
## L5 — tool constraints survive response repair
71+
72+
`createGrokResponsesSparseTerminalBlockRewrite` rebuilds a terminal output from
73+
collected `output_item.done` events and receives a budget but not this request's
74+
tool selection. The undeclared-tool guard answers a different question — whether a
75+
name was declared — so a request with `tool_choice: none` or a narrowed allow-list
76+
can still receive a call the repair put back. Pass the request scope into the
77+
repair and enforce it there. Keep the failure narrow: one forbidden call must not
78+
discard the ordinary text that accompanied it. The empty-catalog case belongs to
79+
the same rule — compatibility is judged on the final request and the final
80+
response, after every removal, rename and translation.
81+
82+
## L6 — a client integration that writes a store nobody reads
83+
84+
A newer client release reads its provider list from a different file than the one
85+
this exporter writes, and the legacy import does not run again once the new file
86+
exists, so an apply that reports success produces no models. Support the store the
87+
running client actually reads, including catalog refresh and disable, or report
88+
the write as ineffective. Deleting the new file to re-trigger a migration is not a
89+
supported remedy. The verification unit is "the client requests the intended
90+
provider", not "the file was written".
91+
92+
## L7 — one developer-role policy in both documents and the code
93+
94+
`structure/providers/chat-compat.md` states the role is forwarded as itself on
95+
every destination; `docs-site` states an unset setting sends `system`; the two
96+
code paths differ again. Whoever fixes this area next picks one of them and
97+
reintroduces the regression. Make the three agree after L2 and L3 settle, and
98+
derive the statement from the code where a test can hold it.
99+
100+
## L8 — one resend budget per logical request
101+
102+
The ambiguous-resend gate landed with one operator grant per request. The
103+
composition still needs evidence: first send, reset, replacement, disconnect after
104+
`response.created`, then the combo candidate, credential refresh and 429 legs.
105+
Observe two separate numbers — physical sends, and sends of a turn that may already
106+
have executed. The neighbouring retry issues are not closed by this lane and stay
107+
open with their remaining scope recorded.
108+
109+
## Out of scope
110+
111+
A lenient finish for a text-only stream with no terminal event is existing
112+
compatibility behaviour with its own regression coverage. Turning every EOF into an
113+
error would be a policy change, not a fix, and is not part of this unit.

0 commit comments

Comments
 (0)