<!-- task=m-stream-evidence-gate-core/15+12_ingress_snapshot_core plan=0 tag=INGRESS_SNAPSHOT -->

# Plan - Bounded lossless ingress snapshot Core

## 배경

RequestRebuilder가 caller unknown field를 보존하면서도 raw body·typed view·temporary rebuild output의 logical retained bytes를 하나의 request-local 상한 아래 관리할 Core primitive가 없다. HTTP/JSON decode와 분리해 ownership/accounting부터 구현한다.

## 분석 결과

- 읽은 파일: `filter_contract.go`, `terminal.go`, `stream_release.go`, approved SDD S11/S12/S18과 OpenAI API contract, config plan 경계.
- `IngressSnapshot`은 endpoint/family, canonical bytes 하나, bounded typed semantic view, builder-issued backing handle ledger, released state를 가진다. accessor는 raw를 filter/observation에 넘기지 않고 registered rebuilder에게만 immutable view를 준다.
- `retained_bytes`는 heap 추정이 아니라 request-owned backing byte/string의 conservative logical 합이다. 같은 builder-issued handle의 backing은 한 번 세고, pointer/`unsafe`/heap introspection으로 alias를 추정하지 않으며, typed view 추가 직후와 rebuild temporary pre/post allocation에서 peak를 검사한다.
- overflow/cancel/close는 canonical/typed/temp references를 idempotent release한다. snapshot은 cross-request cache가 아니며 auth header를 받지 않는다.
- HTTP limit+1과 Chat/Responses patch는 후속 `16` 소유다. 이 plan은 transport-agnostic builder/lease와 deterministic accounting tests만 다룬다.
- `test_env=local`, platform-common profile. build/review closure true; build=`local-fit`, scores=`2/2/1/1/2`, loop-risk=`temporal_state,concurrent_consistency,boundary_contract`, `PLAN-local-G08.md`; official review=`CODE_REVIEW-cloud-G08.md`, Codex `gpt-5.6-sol` xhigh.

## 구현 체크리스트

- [ ] SNAPSHOT-1 canonical/typed backing을 logical byte로 계상하는 immutable request-local snapshot builder를 구현한다.
- [ ] SNAPSHOT-2 rebuild temporary의 pre/post peak guard와 idempotent release/overflow lifecycle을 구현한다.
- [ ] SNAPSHOT-3 shared backing, exact limit+typed overflow, concurrent release/cancel fixtures를 추가한다.
- [ ] SNAPSHOT-4 streamgate unit/race/diff 검증을 수행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다.

## 구현 항목

### [SNAPSHOT-1] snapshot/ledger

- 새 `packages/go/streamgate/ingress_snapshot.go`: `IngressSnapshotBuilder`, immutable snapshot/lease, builder-issued backing handle과 retained/current peak accounting을 정의한다.
- constructor는 `max_bytes`와 canonical source를 먼저 검증하고 typed semantic value를 붙인 직후 다시 검사한다. canonical full copy 둘 이상을 동시에 유지하는 API는 제공하지 않는다.

### [SNAPSHOT-2] rebuild allocation guard

- expected temporary bytes를 reserve한 뒤 실제 output을 commit하는 two-phase guard를 제공한다. 실패 시 temporary/canonical/typed ownership을 정의된 순서로 release하고 provider dispatch 가능한 object를 반환하지 않는다.
- release는 cancel/overflow/normal completion에서 exactly once이며 use-after-release accessor는 stable error다.

### [SNAPSHOT-3] tests

- 새 `ingress_snapshot_test.go`: limit-1/limit/limit+1, raw exact limit+typed overflow, shared backing once, pre/post rebuild overflow, no canonical duplicate, release reference drop/idempotent state, concurrent close/race를 검증한다.

## 의존 관계 및 구현 순서

`12` PASS → SNAPSHOT-1 → SNAPSHOT-2 → SNAPSHOT-3/4. `16`이 HTTP pre-read gate와 endpoint rebuilder를 붙인다.

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| 새 `packages/go/streamgate/ingress_snapshot.go` | SNAPSHOT-1/2 |
| 새 `packages/go/streamgate/ingress_snapshot_test.go` | SNAPSHOT-3 |

## 최종 검증

- `command -v go && readlink -f "$(command -v go)" && go version && go env GOROOT`
- `go test -count=1 ./packages/go/streamgate`
- `go test -race -count=1 ./packages/go/streamgate`
- `git diff --check`

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다.

## 이 파일을 읽는 구현 에이전트에게

구현/test/evidence만 소유하고 active pair를 유지한다. user-review/finalization/roadmap은 official reviewer/runtime 소유다.
