40 lines
2 KiB
Markdown
40 lines
2 KiB
Markdown
# 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/...`
|