# Provider Execution Runtime Contract

## Contract metadata

- id: `iop.execution-runtime`
- boundary: inner
- status: active
- source evidence:
  - `packages/go/execution/types.go`
  - `packages/go/execution/liveness.go`
  - `packages/go/execution/registry.go`
  - `packages/go/execution/emitter.go`
  - `packages/go/execution/failure.go`
  - `apps/node/internal/node/runtime_bridge.go`
  - `apps/node/internal/node/health_probe.go`
  - `apps/node/internal/node/liveness_watchdog.go`
  - `apps/node/internal/transport/session.go`

## Scope

The execution package defines host-neutral provider primitives. It owns provider registration, lifecycle, execution events, typed failures, cancellation, token usage, and the three provider commands `capabilities`, `transport_status`, and `ollama_api`.

`session_id` is an opaque correlation value. It does not select, create, resume, or terminate a process. Repeated requests with the same value are independent executions. Cancellation targets a non-empty `run_id` only.

## Requirements

- Providers implement the narrow `Provider` interface and may expose optional lifecycle, command, or tunnel capabilities.
- Event emitters preserve order and publish exactly one terminal event.
- Registry lookup uses provider identity and returns typed failures for missing or unavailable providers.
- Callers must reject commands outside the closed provider-command allowlist before provider lookup.
- Token usage remains observation data attached to execution or tunnel results.
- `DefaultResponseStallTimeoutMS = 300000` is the documented default. `ResolveStallTimeoutMS(ms)` validates then maps zero to the default; safe positive values pass through, while negative or overflow values return an error.
- `ClassifyRuntimeEvent` returns `start` for `EventTypeStart`, `progress` for non-empty `delta`/`message` or non-terminal usage, `terminal` for `complete`/`error`/`cancelled` (before usage check), and `none` for empty/unknown events.
- `ClassifyProviderTunnelFrame` returns `progress` for `response_start` (with or without headers) and non-empty `body`, `terminal` for `end`/`error` (before payload check), `progress` for `usage`, and `none` for empty/unknown frames.
- `ValidateStallTimeoutMS(ms)` rejects negative values and values exceeding `maxSafeStallTimeoutMS`; zero is allowed (use default).
- `NodeProviderConf.EffectiveResponseStallTimeoutMS()` returns the effective timeout for a provider candidate.
- `RunRequest.ResponseStallTimeoutMS` and `ProviderTunnelRequest.ResponseStallTimeoutMS` carry the selected provider's effective timeout; zero on the wire means the Node applies the documented default.
- The Node wire boundary normalizes zero to `300000` and rejects negative or overflow values before router/provider invocation.
- `response_stalled` is a stable typed failure. Its allowlisted metadata includes the failure code, the joined three-way exact-target health evidence (Edge-visible `provider_health` status and normalized `liveness_classification`), idle duration, Node-owned run/attempt identity, the local close fence, adapter, target, and an optional connection-scoped `health_observation_seq`; caller metadata cannot override these values, and no raw payload, credential, or recovery signal is admitted.
- The Node watchdog starts from attempt admission, resets only on the documented progress dispositions, stops on provider terminal, and emits one typed stall terminal. It does not retry providers or infer recovery eligibility. `Retryable=true` means only that the local provider ownership fence was confirmed within the bounded close grace.
- After the watchdog claims a stall it joins two independent bounded outcomes without extending either serially — the fixed close-grace fence and the exact-target health probe — then assembles exactly one allowlisted terminal. The joined `liveness_classification`/`provider_health` pair is exactly `request_stalled`/`available`, `provider_unhealthy`/`unavailable`, or `health_unknown`/`unknown` (fail-closed default). Provider availability observed here is evidence only: it never resets progress, changes the fence, revives output, or authorizes retry, and late provider output stays fenced.
- `health_observation_seq` is a connection-scoped monotonic sequence sourced from the transport Session. A new connection starts at zero, so the first finalized observation is one; normalized and tunnel observations on the same connection share the source and receive unique, increasing values under concurrency. Internal or unbound execution paths omit the key entirely and never encode a process-global generation.

## Health probe contract

The execution package owns the stable, fail-closed probe outcome vocabulary consumed by Node terminal assembly. It is the typed three-way boundary between an inconclusive probe and a definitive provider-health classification; nothing else maps provider probe results to health.

- `ProviderHealth` is the stable normalized value: `request_stalled`, `provider_unhealthy`, or `health_unknown` (fail-closed default).
- `LivenessClassification` is the stable observable category a probe outcome reduces through: `available`, `unavailable`, `timeout`, `error`, `unsupported`, `unknown`, and `identity_mismatch`.
- `ProbeOutcome` is the typed, target-aware input; `ClassifyProbeOutcome` reduces it to a classification and `NormalizeProbeOutcome` maps it to health. The mapping is exactly: available → `request_stalled`; a validated matching unavailable result → `provider_unhealthy`; every error, timeout, unsupported adapter, unknown status, empty/mismatched adapter or target, and instance mismatch → `health_unknown`.
- A returned error takes precedence over any reported status, so endpoint construction, request/network, non-success HTTP, and decode failures can never be confused with a positive exact-target-absent result.
- The Node probe coordinator (`ProbeHealth`) roots its own five-second bounded context from the background, re-checks that deadline/cancellation after the probe returns, validates exact adapter and target identity (including a pinned instance key when set), and feeds only the typed normalizer. It never copies arbitrary provider metadata.
- `ResolveProbeFunc` returns `nil` for an adapter that does not implement `ProviderProber`; a `nil` hook makes `ProbeHealth` fail closed to `health_unknown` without invoking any endpoint.

Probe completion is evidence only. The probe itself must never reset original request progress, change the attempt fence, authorize retry, sequence the watchdog terminal, drive the Edge overlay, or infer recovery. Node owns the stall-terminal join and the connection-scoped `health_observation_seq`; Edge reception-generation binding, stale-observation validation, the Edge health overlay, candidate exclusion, retry, recovery, and configuration remain owned by later slices.

## Prohibited ownership

The package must not own interactive shells, persistent processes, terminal emulation, working-directory mutation, resumable conversations, local quota probing, or arbitrary host command execution. It must not import application-internal packages or generated transport types.

## Verification

- `go test -count=1 ./packages/go/execution`
- `go test -race -count=1 ./packages/go/execution`
- `go vet ./packages/go/execution`