[ztelur]

Which issue or RFC does this PR close?

Implements the Rust gateway side of the design in #2199 and consumes the external-executor contract from #2264.

Depends on #2264 (/v1/context/check two-phase contract and include_reuse). This PR adds a new gateway/ directory only and does not touch any existing module; it can be reviewed and merged after #2264 lands.

This PR adds one: a self-contained Rust workspace that acts as that external executor, verified end-to-end against a real PowerContext Server over UDS with real upstream providers.

What changes are included in this PR?

A new gateway/ directory (Rust workspace, 7 crates, ~3.7k lines, zero changes to existing Python code):

• Two-phase gate executor: check(before_send) → send admitted bytes → check(before_release) → release. Opaque bindings thread the phases (request_binding must equal the send-phase binding); HTTP success alone is never approval; unknown never becomes allow.
• Memory injection: per user message, calls prepare with include_reuse, injects the returned prepared context verbatim into the current user message, and declares the exact UTF-8 byte range in prepared_contexts for Core-side digest verification. Tail-only injection keeps the client-owned prefix byte-stable (KV-cache friendly, verified with DeepSeek cached_tokens).
• Sedimentation: after a released turn, synchronously captures the transcript via capture_content_source with an idempotent source_id derived from the release binding. Blocked/degraded turns are never captured. The full loop (conversation → capture → background extraction → prepare recall in a new session) was verified end-to-end.
• Deployment forms: combined (Rust owns the public TCP port; Core listens only on a private UDS; all non-/gateway routes reverse-proxied over UDS) or standalone (TCP). Pooled hand-rolled HTTP/1.1-over-UDS client with timeouts, stale-connection retry, and chunked/content-length framing regression tests.
• OpenAI-compatible ingress (/gateway/v1/chat/completions and /gateway/v1/responses, same format in and out), streaming ingestion with strict buffering, upstream status/content-type fidelity.
• Middleware chain (GatewayMiddleware trait) with resource limits (body precheck + concurrency semaphore) and request-id propagation aligned with HttpRequestIdMiddleware.

Contract findings from real integration (relevant to #2264 review):

1. External executors have no usage-reporting endpoint — provider usage collected by a gateway cannot flow back to Core statistics.
2. The public check carrier withholds streaming payloads (streaming_unsupported), so external executors are effectively non-streaming under strict mode.
3. prepared_contexts and ModelJsonTextLocation.schema are required wire fields that are easy to miss (both cost us a 422 during integration).

Are there any user-facing changes?

No changes to existing APIs, storage, or behavior. This adds an optional component: a gateway/ Rust workspace, off by default, not wired into packaging or the Server. Existing users are unaffected.

How was this change tested?

• cargo clippy --workspace --all-targets: zero warnings. cargo test: 29 tests — failure-semantics table (gate unavailable/withhold terminal/bounded retry/indeterminate no-resend/malformed never degrades/non-UTF-8 never released/blocked turns never sediment), renderer fidelity (no timestamps or request ids injected), prepared-context byte-range declaration, UDS connection-pool correctness over a real Unix socket.
• Live integration tests against a real Server (tests/live_context_check.rs, skip gracefully when unreachable): real signed bindings, cross-scope binding rejection, send vs correlation deadline separation.
• Manual end-to-end against a real Server over UDS with two real upstream providers (DeepSeek and GLM via an approved profile): per turn exactly check ×2, prepare ×1, capture ×1 in Server logs; forbidden content blocked with zero sends; memory injected in a fresh session answered from previously sedimented facts.

AI usage statement

AI-assisted development (ZCode, GLM). All code was reviewed, compiled, tested, and validated end-to-end against a real PowerContext Server and real model providers as described above.

[CLAassistant]

All committers have signed the CLA.

[hidb4ai]

Reviewed commit 0572eca. The inline findings cover duplicate sends, destination/admission enforcement, unsafe degradation, wire compatibility, and ineffective resource limits; I do not recommend merging this head.

The reproductions use the actual gateway binary or transport over local HTTP sockets, plus scripted executor fault probes. They do not establish real-provider or real-Core acceptance. The License Header check also fails on 38 added files. The documented Core dependency #2264 is currently closed without merge, and this branch does not supply its /v1/context/check contract.

[hidb4ai]

The gateway dependency is now provided by the split PRs: #2313 supplies prepare/include_reuse/check on top of #2311, and #2312 supplies the combined-deployment UDS listener. #2314 and #2315 concern internal operation encoding and its evaluation; they do not replace the Rust executor's send/release responsibilities. The earlier reference to #2264 being closed should be read with these replacements in view.

I reviewed the latest heads together (#2311 5789b9b, #2312 2e20bcc, #2313 d06ecff, #2314 2d1cdc7, #2315 d931b0c). They compose cleanly in an isolated local review checkout. Actual Core/Gateway processes passed the basic Chat, Atomic Memory injection/capture, and authenticated UDS/API/MCP paths against SQLite and a local HTTP upstream. The existing gateway findings remain; the two additional integration failures are below. No live-provider quality, billing, or background extraction acceptance is claimed.

[hidb4ai]

Re-reviewed bd4ee5b6, including real Gateway/Core (#2313 328f6680) integration with SQLite and a local upstream. The retry, redirect, tool-message, Responses text, nonstream buffer, and pristine-request degradation fixes address the original reproductions. Follow-up evidence is in the existing deadline, request-limit, retention, reuse-assembly, and CI threads. Two additional issues are below. Blocking correctness and CI issues remain.

[hidb4ai]

[P2] Preserve supported Chat request controls

A running-Gateway HTTP probe accepted max_completion_tokens:16, a strict response_format JSON schema, and tool_choice:"none" alongside tool definitions. The actual upstream payload instead contained max_tokens:1024 and the tools, with all three controls removed. The same budget rewrite also passes through the real Core, so admission does not restore the caller's requested limit. This increases the output budget, removes structured-output enforcement, and restores default automatic tool selection. Preserve supported controls through final rendering, or reject unsupported fields before admission instead of accepting them and silently changing their meaning.

[hidb4ai]

Rechecked at e59f16cb: response_format and tool_choice now survive, and the numeric token limit is retained. However, max_completion_tokens:16 is still rewritten to max_tokens:16 by OpenAiChatRenderer (render.rs:96), with the original field absent at the loopback upstream. This is not a compatible alias for o-series models: the OpenAI API contract explicitly excludes them from max_tokens. Preserve which supported token-limit field the caller used through canonicalization/rendering; otherwise valid reasoning-model requests still fail after changing only the base URL.

[hidb4ai]

Rechecked at 6406eafb: omitting a token limit no longer injects 1024, but the explicitly supplied field is still changed. The actual Gateway receives model:"o3", max_completion_tokens:16; both the Core-check payload and the upstream POST contain max_tokens:16 with max_completion_tokens absent. OutputLimits retains only the number, and OpenAiChatRenderer always writes max_tokens. Please preserve which supported field the caller supplied; the o-series incompatibility from the earlier reply remains.

[hidb4ai]

Rechecked at 2e839cba: the renderer now supports token_limit_field, but to_canonical_chat() always sets it to None (ingress.rs:290). A fresh HTTP probe still receives max_completion_tokens:16 and sends max_tokens:16 to both Core checking and the upstream. The new renderer test manually sets the field, so it does not exercise this missing ingress mapping. Populate the field from the supplied Chat request and verify it through the actual ingress-to-wire path.

[ztelur]

根因是批量补构造点时 token_limit_field 被意外覆盖为 None。已恢复条件赋值。端到端验证：客户端发 max_completion_tokens:16 → 上游收到 max_completion_tokens:16，无 max_tokens 字段。测试：max_completion_tokens_field_name_preserved

[hidb4ai]

Re-reviewed c5262d94. The streaming concurrency permit, complete-allow validation, post-capture expiry, and Responses store:false fixes address the tested reproductions. The new continuation-loss finding is inline; I am also adding real-Core evidence to the existing HTTP-rejection/degradation thread. The existing unconfigured Responses destination, Chat token-field rewrite, UDS/SSE parsing, and CI integration findings remain. This head is not ready to merge.

[hidb4ai]

Re-reviewed 6406eafb. The implicit Responses destination and explicit Core-rejection degradation are fixed; real Core also confirms that previous_response_id now withholds without sending. One additional capture data-loss issue is inline. Follow-up replies cover the remaining Chat token-field rewrite, conversation history loss, mixed SSE framing, and UDS response-budget bypass. The existing CI integration failures also remain. This head still needs changes.

[hidb4ai]

[P2] Preserve typed user text when deriving the captured transcript

last_user_text() returns None for supported Chat content parts such as [{"type":"text","text":"alpha port"}], so the caller turns the user input into an empty string. With the actual Gateway and current Core (252ecac0b) using SQLite, this request passed both checks and returned 200; /v1/sources/content accepted the transcript with 202, and reading Sources confirmed "user":"" despite the upstream receiving the original text. The same helper also skips prepare entirely with injection enabled; the equivalent scalar-string request recalls memory and captures the correct user text. Handle supported text-part content when deriving the recall query and transcript so a valid representation change does not silently discard user evidence.

[ztelur]

last_user_text() 新增 typed content parts 分支——当 content 为 [{"type":"text","text":"..."},...] 形态时，提取并拼接所有 type=="text" 的 text 字段

[hidb4ai]

Rechecked at 2e839cba: query extraction and persisted user text are fixed, but typed-content injection still exits at executor.rs:411-414. In the real Core/SQLite replay on 1e8c12aa (the executor is byte-identical in this head), single and multiple text parts received a successful prepare with valid recalled memory, yet the upstream received only the original input and before_send.prepared_contexts was empty. The scalar control injected that same context successfully. Support insertion into typed text content and declare its exact rendered byte location so successful recall becomes model-visible.

[ztelur]

enrich() 现在只修改 type=="text" 的部件注入记忆，所有非文本部件（image_url 等）原样保留——不再丢弃。守护测试：mixed_content_preserves_non_text_parts_during_injection（text + image 混合 → 上游同时收到注入文本和原始 image）

[hidb4ai]

Rechecked at 92dafe81 with the actual Core (252ecac0b) and SQLite: non-text parts are now preserved, but pure typed-text requests regress to HTTP 503 when recall succeeds. For content:[{"type":"text","text":"alpha port"}], prepare succeeds, then /v1/context/check returns 422 with zero upstream sends because the declared pointer remains /messages/0/content, which now resolves to an array. The scalar-string control still succeeds. Changing only the submitted pointer to /messages/0/content/0/text makes the single-part Core check allow. With two text parts, the mapper injects the block into both parts but declares only one location, so correcting the first pointer alone still returns 422. Declare the exact rendered text location for every injected block, or inject once and declare that one location; cover this with real Core validation rather than an always-allow gate mock.

[ztelur]

状态同步：head 在我审查后从 841abacb 漂到 c5262d94（增量只有 tests/executor_semantics.rs +137，且 git diff 841abacb c5262d94 --name-only 只列这一个文件），所以之前四条行内评论的锚点与结论都仍然成立，不需要重开线程：

• uds_gate_client.rs:366 [P1]：gate 返回非 2xx 被判成 GateUnavailable → 走 PassthroughWithoutMemory，绕过全部检查。
• ingress.rs:270 [P2]：缺省 max_tokens 被填成 1024，静默截断。
• main.rs:175 [P2]：启动只读 context_protection.enforcing，缺该成员的 Core 照样被接受。
• prepare.rs:59 [P2]：limit: 8 写死，runtime.context_assembly_max_entries 调低后静默失效。

Merge 结论：暂不可合入。 除上面四条外，同页还有多条 P1（ingress.rs:63 的 store 丢失、main.rs:110 的 Responses 路由缺少显式目标端点）处在 open 状态；作者已回复多条 P2 的修复，但 P1 尚未落地。建议按「先修 gate 错误分类 → 再补 Responses DTO 字段 → 最后处理写死上限」的顺序收，收完后我再逐条复核。

列出的全部六条均已修复：

P1 gate 非 2xx → GateUnavailable → 降级（93519d99）：新增 GateError::GateRejected(u16)；HTTP/UDS 客户端非 2xx 归此类别；executor 降级只匹配 GateUnavailable——测试：gate_rejected_does_not_degrade
P2 max_tokens 默认 1024 截断（6406eafb）：OutputLimits.max_output_tokens 改 Option；未传时字段不出现（条件插入）——测试：omitted_token_limit_not_emitted
P2 启动只读 enforcing（6406eafb）：验 check_versions 含 context-check.v1 + payload_versions 含 model-json-payload.v1；缺 → 降级禁用 + 日志报错
P2 limit:8 写死（6406eafb）：PC_GATEWAY_ASSEMBLY_LIMIT 环境变量可配（默认 8，上限 8）
P1 store 丢失（0268866e）：Responses DTO 捕获 + 渲染器输出——测试：store_false_reaches_responses_wire_body
P1 Responses 默认 OpenRouter（93519d99）：移除默认；未配置返回 501 responses_route_disabled
另修复了 previous_response_id 透传（hidb4ai 最新发现）、Chat 控制字段（max_completion_tokens/response_format/tool_choice）、SSE CRLF 分帧、chunk 溢出、RFC3339 小数秒缩放、沉淀用原始用户文本。当前 70 个测试全绿、clippy 零警告

[hidb4ai]

Re-reviewed 2e839cba. The reported mixed-SSE separator, oversized Content-Length read, and original CI orchestration findings are fixed. Existing-thread replies cover the remaining typed-content injection gap, HTTP token-field rewrite, and cumulative chunked-body budget, including an exact-budget framing regression. Responses conversation references are still silently dropped. One workflow permission mismatch is inline; it is based on the YAML and documented permissions contract, not an observed Actions execution. This head still needs changes.

[hidb4ai]

[P2] Grant the permission required by the nested scope workflow

On workflow_dispatch, inputs.suites is empty, so changes calls ci-changes.yml, which requires actions: read. This caller grants only contents: read; unspecified permissions become none, and nested workflows cannot elevate them. The manual Gateway entry point therefore cannot supply the child workflow's required permission. Grant actions: read at the calling boundary. This is a source-level contract mismatch; the current GitHub run is awaiting approval, so I am not reporting an observed runner failure.

[ztelur]

gateway.yml 的 permissions 从仅 contents: read 改为同时包含 actions: read，满足 ci-changes.yml 嵌套调用的权限要求

[hidb4ai]

@ztelur Following up on the latest review: the head is still 2e839cba, and these five items need attention:

• Typed content: recalled memory is not injected into typed user messages.
• Chat token limits: HTTP ingress still rewrites max_completion_tokens to max_tokens.
• Responses history: conversation references are silently dropped.
• UDS response limits: the cumulative chunked budget is still bypassed, while a valid single 8 MiB chunk is rejected.
• Workflow permissions: the manual Gateway workflow lacks the actions: read permission required by its nested workflow (a source-level finding).

Please address these and reply in the existing threads with the fix commits and relevant regression evidence when ready for another review.

[hidb4ai]

Re-reviewed d05f4e6f. Fresh HTTP probes confirm that the Chat token-limit field is now preserved; pure typed-text injection and workflow permissions are also fixed. The injection branch still discards non-text content before admission, as described inline. The cumulative UDS chunked budget and single-chunk boundary remain broken, and Responses conversation references are still dropped. This head still needs changes.

[hidb4ai]

[P2] Preserve non-text parts when injecting recalled context

This replaces the entire content array with a string assembled from .text values. A real Core/SQLite probe on 6a427536 (this executor is unchanged here) used a user message containing text plus an image_url part. Direct Core checking withheld it as content_unsupported; with injection enabled and matching memory, Gateway removed the image before admission, obtained allow, and returned 200. The upstream received only recalled context and text. Preserve the original non-text parts during insertion so unsupported content remains visible to Core instead of silently disappearing. Pure typed-text cases pass; the regression case needs a mixed content array.

[ztelur]

enrich() 不再将 typed parts 的整个 content 数组替换为单字符串。现在只修改 type=="text" 的部件（在 text 字段前注入记忆块），所有非文本部件（image_url 等）原样保留

[hidb4ai]

Re-reviewed 92dafe81: the mixed-content image loss is fixed. Real Core/SQLite validation exposes a typed-text injection regression, detailed in the existing thread: valid text-part requests now fail after successful recall. Responses conversation references and UDS chunked limits remain unchanged and unresolved. This head still needs changes.

[AlexStocks]

[P2] 注入块被写进每一条 text 部件，多 text 部件消息会重复注入

第 416 行的注释写的是“只修改第一个 text 部件注入记忆”，但第 426-435 的 map 对每一个 type == "text" 的部件都做了 format!("{block}\n\n{text}")。对 content = [{"type":"text","text":"A"},{"type":"text","text":"B"}] 的最后一条用户消息，外发体变成 {block}\n\nA 与 {block}\n\nB——同一个记忆块出现两次。

可观测后果：

• 注入字节数随 text 部件数线性放大，而 capabilities.limits.payload_bytes 是硬上限，重复块会更早撞线；
• prepared_contexts 只为这条消息记一个 MessageJsonTextLocation，回执/审计记录与实际注入份数不一致。

建议：只对第一个 text 部件前缀（enumerate() 后判断是否已经注入过一次），或先取出第一条文本再拼接，与注释保持一致；并补一条“两段 text 部件”的渲染断言，验证块只出现一次。

[ztelur]

Done

[hidb4ai]

Re-reviewed c2919d67: real Core/SQLite probes now pass for scalar, single-part and multi-part text injection and capture; mixed-content images remain intact and are correctly withheld. The valid single 8 MiB UDS chunk also works. Two issues still need changes: the cumulative UDS body budget still buffers 64 MiB before rejection, and Responses conversation references are still silently dropped (the ingress/rendering code is unchanged). Please address both before merge.

[ztelur]

Re-reviewed c2919d67: real Core/SQLite probes now pass for scalar, single-part and multi-part text injection and capture; mixed-content images remain intact and are correctly withheld. The valid single 8 MiB UDS chunk also works. Two issues still need changes: the cumulative UDS body budget still buffers 64 MiB before rejection, and Responses conversation references are still silently dropped (the ingress/rendering code is unchanged). Please address both before merge.

两项已修复（4e55672a + 6075cc6）：

UDS 累计预算：检查在 read_chunked 解析 chunk size 后、读取 chunk 数据前执行。。

Responses conversation：应该修改的是 conversation 参数（与 previous_response_id 不同字段）。现在 DTO 捕获并透传到渲染器输出——Core 能看到 conversation 引用并按需 withhold。守护测试：conversation_field_reaches_wire_body

[hidb4ai]

LGTM