|
| 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