# Service Version Compatibility

A client may be newer than the long-running Omnius daemon it reaches. The
runtime version gate prevents a stale service from quietly accepting work
whose provider, tool, or request contract it does not understand.

## Inspect The Service

```bash
curl -s http://127.0.0.1:11435/version
```

The response contains `package_version`, `api_version`, and
`discovery_schema_version`. Compatibility fields `version`, `boot_version`,
`boot_package_hash`, `node`, and `platform` remain for existing clients.

Inspection endpoints remain available even when the service is too old to run
a new client request: health, version, help, OpenAPI, and discovery.

## Require A Minimum Version

Send a SemVer minimum on execution requests:

```text
X-Omnius-Min-Version: <minimum-compatible-package-version>
```

The gate applies to:

- `POST /v1/run`;
- `POST /v1/chat`, `/api/chat`, and `/v1/chat/completions`;
- `POST /v1/generate` and `/api/generate`;
- `POST /v1/tools/{name}/call`;
- `POST /v1/commands/{cmd}`.

The service checks the precondition before the request handler creates state,
loads a model, calls a provider, or invokes a command/tool.

Responses:

| Condition | Result |
| --- | --- |
| header omitted | normal backward-compatible behavior |
| valid minimum, service satisfies it | request proceeds |
| invalid SemVer | RFC 7807 `400 Bad Request` |
| service older than minimum | RFC 7807 `412 Precondition Failed` |

A `412` is not retryable against the same daemon. Update or reconnect to a
verified compatible Omnius service, inspect `/version` again, and resubmit
only after the precondition can succeed.

## Why Both Check And Header

`GET /version` gives a useful compatibility diagnostic. The header is the
execution-time guard and closes the race between checking a service and
submitting work after that service has been replaced or routed elsewhere.

## Client Rule

Keep the required version in the adapter that constructs Omnius execution
requests. Do not rely on a human-readable npm version, cached install
metadata, or the client's own package version. Compare against the daemon's
reported package version and preserve the execution precondition.