docs: explain bounded proxy spool memory and safe adoption #47

Source engine PR: RandomDevelopment/ci-fleet#163
Status: engine source accepted and merged; actual-template guidance and downstream adoption remain pending.
Original candidate source: 21edcfea2aad1f0e16e01249312bb2eff423b9a5
Reviewed and fully validated successor: 7d08ab3df8d4c3f274e5f8da6bf36e4891819fd5
Base: 49da9d62dfa7527f569e0855b4fb877f6f8c7aed
Merged engine identity: 1c685dacc109597641fd13dfae48606e76f73ee7, merged 2026-11-03T13:52:06Z.
Merged/source tree: a11bbea773b20f0e6d08574c0038275a7460f4ee. REST and local Git verified ordered parents 49da9d62dfa7527f569e0855b4fb877f6f8c7aed and 7d08ab3df8d4c3f274e5f8da6bf36e4891819fd5.

Current acceptance:

• All eight stages passed in https://github.com/RandomDevelopment/ci-fleet/actions/runs/41615505066, attempt 1, on the exact successor/base above. Official nine-member archive and all eight stage hashes verified. Archive SHA256 a40dfd1cefc0b28c86ff9ec8ad1ec5c9ad08cbf0e6c99b942380d3acdf801389; report 1832b840c392af1878ded1fdfc34fb4d5730c95af67aa37fb88898590928e2c1.
• Independent exact-head manual source review approved without actionable source or documentation findings: fix(controller): bound proxy upload file-cache charges ci-fleet#163 (comment). The automatic Codex review service was quota-exhausted; Bugbot was unavailable. Neither supplied approval.
• Current-source two concurrent 1 GiB uploads passed payload/hash and phase assertions, with cgroup peak 24,195,072 bytes, sampled file-cache peak 8,687,616 bytes and zero OOM kills. Full worker export, scoped cleanup and final admission passed. This is source proof, not a live adopted identity.
• The original 21ed proof, failed original run and both 22db attempts retain their separate identities and evidence. No tag/release, template edit, private promotion, live adoption or application retry occurred.

Template scope and gates

The source correction preserves the 128 MiB proxy memory limit, 1 GiB body cap, two upload slots, source binding, maintenance locks and uncertainty handling. It releases disk-spool file-cache pages in bounded windows while receiving and forwarding, and refuses memory-backed temporary spools before forwarding. A file's unlink alone does not release its cgroup memory charge.

Assess docs/UPDATING.md, README.md maintenance/adoption pointers and AGENTS.md for consistent operator guidance. No schema, desired-state, initializer, validator, capability or rollout-evidence field changes are expected. Preserve ordinary policy840, image/runtime pins, capacity, historical release records and existing acceptance holds until a separate reviewed adoption selects an accepted merged engine.

Acceptance checks:

• Link the actual reviewed merged engine identity when it exists; do not describe this candidate as merged or deployed.
• Explain disk-backed temporary storage and unchanged limits. Do not recommend memory/capacity increases or copying a live fix into place.
• Require exact accepted source/image identity and the supported engine -> actual template -> private configuration -> host adoption order. A source proof, current running container or automatic proxy restart is not live recovery.
• Retain the independent daemon/proxy availability and workload protection gates before an application retry. Never clear current-boot uncertainty markers or bypass the proxy.
• Update examples/commands and run applicable documentation checks. Preserve published immutable records.

Related open #44 remains responsible for cleanup ordering and retention acceptance; this issue adds only proxy-spool memory and adoption guidance. No template edit, release, private promotion or live host activation is authorized by this tracking issue.

Historical source-preparation notes

Current fixture-only source successor b102c934e9fc17a769854c178914c1f28ad31106, tree 573b9e9af446308c0354f39b7999d0413230c494, retains the proxy implementation, native regression and operator guide byte-for-byte. It repairs one omitted helper in an existing cleanup fixture after required run41564610251 failed. Exact-head successor review and complete required check remain pending. Native proof keeps the original21edcfea source stamp; no template source edit, suite or live adoption has started.

Current cancellation-correction source 22db077a491733205bb286bcd6fbc042ea09226b, tree 1d1b692f7b51e915eda03227f40ed9c755a9f811, retains the engine proxy implementation and operator guide. Its new memory fixture handles SIGTERM and always attempts owned-container removal after log collection. Both cancellation subcases and the retained cleanup/status cases passed under the installed executor; independent current-head review and complete required check remain pending. Original proof keeps its original source stamp. No template/private/live promotion has occurred.

Exact current source 22db077a491733205bb286bcd6fbc042ea09226b independently reviewed without findings at 2026-11-03T02:48:50.393524Z. All inline findings are resolved with cancellation/cleanup regression evidence. The execution owner is admitting its single complete required engine run through the existing scoped native producer; final result, verified export and cleanup remain required. No template/private/live identity is promoted by this record.