---
id: RAIL-K8S-WP-0002
type: workplan
title: "Version the common workload and derived-rail contract"
domain: financials
repo: rail-kubernetes
status: finished
owner: codex
topic_slug: railiance
created: "2026-07-26"
updated: "2026-07-26"
state_hub_workstream_id: "028b0456-3e54-4539-b563-0eec012c3ecb"
---

# RAIL-K8S-WP-0002 - Version the common workload and derived-rail contract

## Goal

Make `rail-kubernetes` the explicit versioned base contract used by default for
platform workloads and inherited by justified specializations such as
`rail-knative`.

## T01 - Version the base rail declaration

```task
id: RAIL-K8S-WP-0002-T01
status: done
priority: high
state_hub_task_id: "3a2c7e33-f1d4-42dd-b45a-08a5835a22cf"
```

Add composition kind, contract version, required capabilities, and readiness
state without changing current lifecycle behavior.

2026-07-26: `declarations/rail.yaml` now declares base composition, contract
`1.0.0`, required substrate capabilities, verified readiness, and the default
platform/managed-application scope.

## T02 - Add the rail-neutral workload and binding schemas

```task
id: RAIL-K8S-WP-0002-T02
status: done
priority: high
state_hub_task_id: "61e92217-b7d9-4a53-ae28-1c60eb6a201e"
```

Separate common workload identity, criticality, dependencies, security,
health, evidence, and recovery requirements from rail-specific bindings.

2026-07-26: Added the common workload, rail-binding, and derived-rail JSON
schemas plus a valid Kubernetes-default example.

## T03 - Add compatibility conformance

```task
id: RAIL-K8S-WP-0002-T03
status: done
priority: high
state_hub_task_id: "06e1aa1f-2111-4be5-9b4b-28fd440eb7c3"
```

Provide an idempotent validator suitable for local, agent, CI, and scheduled
execution. Reject incompatible base contracts, missing ownership, and
unsupported substrate capabilities.

2026-07-26: Added `tools/validate_contracts.py`. It validates base/derived rail
shape and common workload JSON Schema without accessing runtime credentials.

## T04 - Preserve the Kubernetes default

```task
id: RAIL-K8S-WP-0002-T04
status: done
priority: medium
state_hub_task_id: "54793f28-a417-43c4-9a02-aa55199fca9f"
```

Document and test that workloads without a justified specialization continue
to bind to `rail-kubernetes`.

2026-07-26: The base declaration identifies Kubernetes as the default for
platform workloads and managed applications; the example uses that binding.