# Edge-Node Runtime Wire Contract

## Contract metadata

- id: `iop.edge-node-runtime-wire`
- boundary: inner
- status: active
- source evidence:
  - `proto/iop/runtime.proto`
  - `apps/edge/internal/transport/`
  - `apps/node/internal/transport/`
  - `apps/node/internal/bootstrap/runtime_supervisor.go`
  - `apps/edge/internal/node/mapper.go`
  - `apps/node/internal/adapters/config_set.go`

## Scope

This contract covers the internal protobuf socket between Edge and Node: registration, dispatch readiness, reconnect fencing, normalized provider runs, provider HTTP tunneling, cancellation, provider commands, and runtime config refresh.

## Required behavior

- A successful registration claims a pending connection. Dispatch starts only after the current connection completes the ready handshake.
- Reconnect fencing compares the node identity and current connection so stale callbacks cannot change live ownership or release a new lease.
- `RunRequest.adapter` and `target` identify provider execution. `session_id` is opaque correlation only; repeated values do not reuse execution state.
- `RunEvent` preserves ordered start, delta, and exactly one terminal outcome.
- `ProviderTunnelRequest` and ordered frames carry raw provider HTTP/SSE traffic separately from normalized run events. Usage frames are observation-only.
- `CancelRequest` accepts a non-empty `run_id` and cancels that run only.
- `NodeCommandRequest` admits only `CAPABILITIES`, `TRANSPORT_STATUS`, and `OLLAMA_API`; unsupported commands fail before provider lookup.
- Node config payloads contain provider adapter instances and runtime limits only.
- Removed field numbers and names remain reserved in protobuf source.

## Prohibited behavior

The wire must not expose persistent process management, interactive terminal control, working-directory execution context, conversation resume, local quota probes, arbitrary host commands, or direct Control Plane/Client scheduling.

## Verification

- `make proto`
- `make proto-dart`
- `go test -count=1 ./apps/node/... ./apps/edge/...`