<!-- task=m-node-provider-execution-liveness-recovery/05+04_failure_wire_contract plan=2 tag=API milestone-task=failure-handoff -->

# Typed Execution Failure Wire Foundation

## For the Implementing Agent

Implement only this wire foundation, run every verification command, and fill all implementation-owned sections of `CODE_REVIEW-cloud-G07.md` with actual notes and raw command output. Keep active files in place and report ready for review; finalization belongs to the code-review skill. If blocked, record exact blocker evidence, attempted commands/output, and resume conditions only. Do not ask the user, call user-input tools, create control-plane stop files, classify the next state, archive logs, or write `complete.log`.

## Background

Node already creates a typed `response_stalled` failure, but the protobuf envelopes flatten or omit it. S04 first needs a backward-compatible common wire model that every generated consumer can compile before Node begins populating it.

## Archive Evidence Snapshot

- Predecessor: `agent-task/archive/2026/08/m-node-provider-execution-liveness-recovery/04+03_health_evidence/complete.log`; final verdict PASS.
- Refined parent: `plan_local_G07_1.log` and `code_review_cloud_G07_1.log` in this directory; unimplemented, no verdict or implementation evidence.
- This child retains parent API-1 only. The dependent Node mapper child owns present/absent semantic round-trips.

## Analysis

### Files Read

- `proto/iop/runtime.proto`, `proto/gen/iop/runtime.pb.go`
- `apps/client/lib/gen/proto/iop/runtime.pb.dart`, `apps/client/lib/gen/proto/iop/runtime.pbenum.dart`, `apps/client/lib/gen/proto/iop/runtime.pbjson.dart`, `apps/client/lib/gen/proto/iop/runtime.pbserver.dart`
- `packages/go/execution/failure.go`, `packages/go/execution/types.go`
- `Makefile`, `agent-test/local/client-smoke.md`, `agent-test/local/node-smoke.md`, `agent-test/local/edge-smoke.md`, `agent-test/local/control-plane-smoke.md`

### SDD Criteria

- SDD: `agent-roadmap/sdd/operational-observability-provider-management/node-provider-execution-liveness-recovery/SDD.md`; status `[승인됨]`; `milestone-task=failure-handoff`.
- S04/Evidence Map S04 requires one raw-free optional failure shape on both `RunEvent` and `ProviderTunnelFrame`. This child establishes that compatibility contract; child `06+05_failure_wire_mapping` supplies the path semantics and assertions.

### Verification Context

- Archived predecessor 04 is PASS. `protoc` 29.3 and `protoc-gen-go` v1.36.11 are available; `protoc-gen-dart` must be installed with `flutter pub global activate protoc_plugin` if still absent before verification.
- Generation, Dart client tests, repository consumer compilation, vet, and diff checks are local deterministic evidence. No external runner is required.

### Test Coverage Gaps

- Generated Go/Dart consumers do not yet contain `ExecutionFailure` or optional envelope fields. Semantic population remains deliberately absent until the dependent child.

### Symbol References

- No symbol is renamed or removed. New fields are optional and use new protobuf field numbers.

### Split Judgment

- This is the stable producer child from the refined wire parent. It can PASS on schema generation and consumer compatibility independently; `06+05_failure_wire_mapping` consumes the generated fields and waits for this PASS.

### Scope Rationale

Do not populate failures, interpret Edge eligibility, mutate health, release leases, or dispatch recovery. This child changes only the common type system and checked-in generated outputs.

### Final Routing

- `evaluation_mode=isolated-reassessment`; finalizer=`finalize-task-policy.sh pair`.
- Build closure true, scores `(2,0,2,1,2)`, grade G07, route `local-fit` -> `PLAN-local-G07.md`.
- Review closure true, scores `(2,0,2,1,2)`, grade G07, route `official-review` -> `CODE_REVIEW-cloud-G07.md` (`codex`, `gpt-5.6-sol`, `xhigh`).
- `large_indivisible_context=false`; positive loop risk: `boundary_contract` (1). `review_rework_count=0`, `evidence_integrity_failure=false`.

## Implementation Checklist

- [ ] API-1 adds one safe optional non-recursive failure message to both protobuf envelopes and the in-memory tunnel type without changing existing field numbers.
- [ ] Regenerate checked-in Go and Dart bindings through repository workflows and prove all generated consumers compile.
- [ ] Run generation, client, repository/package, vet, and diff verification with fresh output.
- [ ] Fill implementation-owned sections in CODE_REVIEW-*-G??.md with actual implementation notes and verification output.

### [API-1] Add the typed failure wire model

**Problem:** `RunEvent` carries only an error string and `ProviderTunnelFrame` has no typed failure, so Edge cannot receive the existing `execution.Failure` without an additive schema contract.

**Solution:** Add non-recursive protobuf `ExecutionFailure{code,message,retryable,metadata}`, optional `RunEvent.failure=13`, and optional `ProviderTunnelFrame.failure=15`. Mirror the pointer in the in-memory tunnel frame and regenerate Go/Dart bindings. Do not add a recursive cause or renumber existing fields.

**Modified Files and Checklist:**

- [ ] `proto/iop/runtime.proto`: append the common message and optional envelope fields.
- [ ] `proto/gen/iop/runtime.pb.go`: regenerate Go bindings and descriptors.
- [ ] `apps/client/lib/gen/proto/iop/runtime.pb.dart`: regenerate Dart messages.
- [ ] `apps/client/lib/gen/proto/iop/runtime.pbenum.dart`: regenerate Dart enums.
- [ ] `apps/client/lib/gen/proto/iop/runtime.pbjson.dart`: regenerate Dart descriptors/JSON.
- [ ] `apps/client/lib/gen/proto/iop/runtime.pbserver.dart`: regenerate Dart server companions.
- [ ] `packages/go/execution/types.go`: add the tunnel-side typed failure pointer with ownership comments.

**Test Strategy:** Generated-output freshness plus all Go/Dart consumer builds are the child oracle; semantic present/absent fixtures belong to the dependent mapper child.

**Verification:** `make proto && make proto-dart && make client-test` must PASS after installing `protoc_plugin` if required.

## Dependencies and Execution Order

1. `04+03_health_evidence` is satisfied by `agent-task/archive/2026/08/m-node-provider-execution-liveness-recovery/04+03_health_evidence/complete.log`.
2. This child must produce `complete.log` before `06+05_failure_wire_mapping` starts.

## Modified Files Summary

| File | Item |
|------|------|
| `proto/iop/runtime.proto` | API-1 |
| `proto/gen/iop/runtime.pb.go` | API-1 |
| `apps/client/lib/gen/proto/iop/runtime.pb.dart` | API-1 |
| `apps/client/lib/gen/proto/iop/runtime.pbenum.dart` | API-1 |
| `apps/client/lib/gen/proto/iop/runtime.pbjson.dart` | API-1 |
| `apps/client/lib/gen/proto/iop/runtime.pbserver.dart` | API-1 |
| `packages/go/execution/types.go` | API-1 |
| `agent-task/m-node-provider-execution-liveness-recovery/05+04_failure_wire_contract/CODE_REVIEW-cloud-G07.md` | API-1 |

## Final Verification

Fresh output is required. If `protoc-gen-dart` is absent, first run `flutter pub global activate protoc_plugin`.

1. `make proto && make proto-dart` — generated Go/Dart outputs match the schema.
2. `make client-test` — PASS.
3. `go test -count=1 ./packages/go/execution ./apps/node/... ./apps/edge/internal/transport ./apps/control-plane/...` — all direct Go consumers compile and PASS.
4. `go vet ./packages/go/execution ./apps/node/... ./apps/edge/internal/transport ./apps/control-plane/...` — no diagnostics.
5. `go test -count=1 ./...` — all checked-in Go protobuf consumers PASS.
6. `git diff --check` — no whitespace errors.

After completing all code changes, fill implementation-owned sections in `CODE_REVIEW-*-G??.md`.
