browser/openspec/changes/replace-run-endpoints-with-redis-runtime-registry/specs/redis-runtime-session-registry/spec.md

ADDED Requirements

Requirement: Redis-backed runtime session registry is required

The system SHALL use Redis as the runtime session registry in development, test, and production environments, and SHALL NOT use an in-memory registry fallback for normal runtime registration, heartbeat, token validation, or job routing.

Scenario: Platform starts without Redis

• WHEN Platform starts or checks health while Redis is unavailable
• THEN runtime registry health is reported unavailable and runtime dispatch operations fail safely without assigning jobs to Runs

Scenario: Automated tests exercise Redis registry behavior

• WHEN tests cover Run registration, heartbeat expiry, token validation, or job claim routing
• THEN those tests use an isolated Redis database or key prefix rather than a memory-only registry

Requirement: Run registration creates an ephemeral Redis session

The system SHALL authenticate generated Runs with durable component credentials and SHALL store only a short-lived Redis session lease for the live Run connection.

Scenario: Valid generated Run registers

• WHEN a Run submits a hello request with a valid server instance ID, component kind, component key generation, registration proof, version, target, capabilities, and capacity
• THEN Platform authenticates the durable component key and writes a Redis session lease scoped to that server/component identity

Scenario: Registration supersedes prior live session

• WHEN a second valid Run registers for the same server/component identity
• THEN Platform rotates the live Redis session token and the previous session token no longer authorizes heartbeat or job operations

Scenario: Invalid token is rejected

• WHEN a Run presents an invalid registration proof or stale component key generation
• THEN Platform rejects registration and does not create or renew a Redis session lease

Requirement: Heartbeat leases expire without startup cleanup

The system SHALL represent runtime online state through Redis TTL leases that are renewed by heartbeats and naturally expire without Platform startup cleanup.

Scenario: Heartbeat renews lease

• WHEN a registered Run heartbeats with the current session token before the Redis TTL expires
• THEN Platform renews the Redis lease and updates the safe capability/capacity snapshot

Scenario: Run stops heartbeating

• WHEN a Run stops heartbeating beyond the configured expiry window
• THEN Redis expires the session keys and Platform reports that runtime connection as offline

Scenario: Platform restarts

• WHEN Platform restarts while Redis still contains live session keys
• THEN Platform resumes token validation and routing from Redis without scanning or cleaning stale keys at startup

Scenario: Redis loses session data

• WHEN Redis restarts or evicts runtime session keys
• THEN Platform treats affected Runs as offline until they register again and does not mutate durable server or job records solely because the Redis lease disappeared

Requirement: Runtime jobs target server components instead of run endpoints

The system SHALL route durable runtime jobs by logical server/component target and SHALL NOT require a durable run endpoint row to create, validate, claim, or complete machine-side runtime work.

Scenario: Job is queued for a server Run

• WHEN Platform queues lifecycle, config, file, log, or protected-request work for a server Run
• THEN the durable job target identifies the server instance and run component rather than a run endpoint ID

Scenario: Run claims work

• WHEN a registered Run claims work with its current session token
• THEN Platform derives the server/component target from Redis and assigns only eligible jobs for that target

Scenario: Run attempts cross-server claim

• WHEN a Run session for one server attempts to claim, acknowledge, report progress, or complete a job targeting another server/component
• THEN Platform rejects the operation and preserves the durable job state

Requirement: Runtime connection projections are safe

The system SHALL expose runtime connection health as a safe projection derived from Redis leases and durable server/component metadata, without exposing session tokens, Redis keys, raw credentials, host paths, or direct sockets.

Scenario: Owner views server runtime health

• WHEN an authorized owner views a server's runtime connection state
• THEN Platform returns safe status, last heartbeat time, version, target OS/architecture, capabilities, capacity, and unavailable reason

Scenario: Runtime session secrets remain hidden

• WHEN Platform Web, plugin pages, or bridge actions request runtime status
• THEN responses exclude session tokens, token hashes, Redis key names, raw component credentials, host paths, and sockets