Independent client/engine versioning with compatibility check

Split release.sh into release-client.sh and release-engine.sh for independent release cadences. Client checks engine version on first API call and hard-fails if engine is below MinEngineVersion. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-28 15:59:16 +00:00
parent b04823e67b
commit 528a09ca90
14 changed files with 729 additions and 93 deletions
@@ -0,0 +1,25 @@
+## MODIFIED Requirements
+
+### Requirement: Compose files for deployment
+
+The project SHALL provide Docker Compose files for single-command deployment. Compose files SHALL use `build:` context for local development. Release notes SHALL document the versioned image tag for users pulling pre-built images.
+
+#### Scenario: Start NVIDIA deployment
+- **WHEN** an admin runs `docker compose -f compose.nvidia.yaml up -d`
+- **THEN** the engine SHALL start with GPU access, bind-mount the data directory, and be reachable on the configured port
+
+#### Scenario: Start ROCm deployment
+- **WHEN** an admin runs `docker compose -f compose.rocm.yaml up -d`
+- **THEN** the engine SHALL start with GPU access via ROCm device passthrough, bind-mount the data directory, and be reachable on the configured port
+
+#### Scenario: Automatic restart
+- **WHEN** the engine process crashes or the host reboots
+- **THEN** Docker SHALL automatically restart the container (restart policy `unless-stopped`)
+
+#### Scenario: Configure via environment
+- **WHEN** an admin sets environment variables in the compose file (KB_MODEL, KB_API_KEY, KB_DEVICE, etc.)
+- **THEN** the engine SHALL use those values
+
+#### Scenario: Pre-built image deployment
+- **WHEN** an admin wants to use a pre-built engine image without building from source
+- **THEN** the engine release notes SHALL include the exact `docker pull` command with the versioned tag (e.g. `docker.dcglab.co.uk/dcg/kb/engine:engine-v2.1.0-nvidia`)
@@ -0,0 +1,13 @@
+## MODIFIED Requirements
+
+### Requirement: Engine status and reindex
+
+The engine SHALL provide status information and support re-embedding all chunks. The `version` field in the status response SHALL always be present and SHALL reflect the engine's release version as read from the `VERSION` file. This field is the contract used by clients for compatibility checking.
+
+#### Scenario: Get engine status
+- **WHEN** a client sends `GET /api/v1/status`
+- **THEN** the engine SHALL return JSON with `version` (string, from VERSION file), model_name, embedding_dim, GPU device info, database stats (document count by type, total chunks, DB size), and queue stats (queued/processing job count)
+
+#### Scenario: Trigger reindex
+- **WHEN** a client sends `POST /api/v1/reindex`
+- **THEN** the engine SHALL re-embed all existing chunks using the currently loaded model and return progress information. This operation SHALL NOT block search queries.
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: Engine version compatibility check
+
+The client SHALL verify that the connected engine meets a minimum version requirement before executing any API command. The minimum required engine version SHALL be embedded in the client binary at build time. If the engine version is below the minimum, the client SHALL print an error message and exit with a non-zero code. There SHALL be no flag to skip or suppress this check.
+
+#### Scenario: Compatible engine version
+- **WHEN** the client connects to an engine reporting version `2.1.5` and `MinEngineVersion` is `2.1.0`
+- **THEN** the client SHALL proceed with the command normally
+
+#### Scenario: Incompatible engine version
+- **WHEN** the client connects to an engine reporting version `2.0.3` and `MinEngineVersion` is `2.1.0`
+- **THEN** the client SHALL print to stderr: `Error: kb client vX.Y.Z requires engine v2.1.0+ (connected engine is v2.0.3)` followed by an upgrade hint, and exit with code 1
+
+#### Scenario: Engine unreachable during version check
+- **WHEN** the client cannot reach the engine's `/api/v1/status` endpoint
+- **THEN** the client SHALL skip the version check and proceed with the original command (the actual API call will surface the connectivity error)
+
+#### Scenario: Version check is cached per session
+- **WHEN** the client has already verified engine compatibility during the current invocation
+- **THEN** subsequent API calls within the same invocation SHALL NOT repeat the version check
+
+#### Scenario: Client version command does not check engine
+- **WHEN** the user runs `kb --version`
+- **THEN** the client SHALL print the client version without contacting the engine
+
+#### Scenario: MinEngineVersion not set
+- **WHEN** the client binary has `MinEngineVersion` set to empty string or `dev`
+- **THEN** the client SHALL skip the version check entirely (development builds)
+
+---
+
+## MODIFIED Requirements
+
+### Requirement: Single static binary with zero runtime dependencies
+
+The Go client SHALL compile to a single static binary with no runtime dependencies. It SHALL support cross-compilation for Linux (amd64, arm64), macOS (amd64, arm64), and Windows (amd64). The build SHALL inject both `Version` and `MinEngineVersion` via ldflags.
+
+#### Scenario: Install on a clean machine
+- **WHEN** a user downloads the `kb` binary for their platform
+- **THEN** they SHALL be able to run it immediately with no additional installs (no Python, no Docker, no shared libraries)
+
+#### Scenario: Version and compatibility info embedded at build time
+- **WHEN** the client is built with `make all VERSION=2.1.0 MIN_ENGINE_VERSION=2.0.0`
+- **THEN** `kb --version` SHALL report `2.1.0` and the compatibility check SHALL use `2.0.0` as the minimum engine version