143 lines
4.2 KiB
Markdown
143 lines
4.2 KiB
Markdown
# Rail Composition Contract
|
|
|
|
Date: 2026-07-26
|
|
Status: Adopted for the second implementation wave
|
|
|
|
## Purpose
|
|
|
|
Define how a specialized Railiance execution rail composes with the default
|
|
`rail-kubernetes` contract without duplicating it.
|
|
|
|
Railiance platform workloads use `rail-kubernetes` by default. A specialized
|
|
rail is justified only when a workload needs materially different execution
|
|
semantics and those semantics cannot be expressed safely as a small workload
|
|
profile.
|
|
|
|
## Rail Kinds
|
|
|
|
Rails have one of two composition kinds:
|
|
|
|
- `base`: owns a complete workload execution contract for a substrate class
|
|
- `derived`: inherits a versioned base-rail contract and owns only its
|
|
specialization
|
|
|
|
`rail-kubernetes` is the default base rail.
|
|
|
|
`rail-knative` is a derived rail:
|
|
|
|
```text
|
|
Kubernetes substrate profile
|
|
-> rail-kubernetes common workload contract
|
|
-> rail-knative activation and revision specialization
|
|
-> rapp-qonto workload binding
|
|
```
|
|
|
|
Knative installation remains an S2 cluster capability. The derived rail owns
|
|
how Railiance workloads use that installed capability.
|
|
|
|
## Required Declaration Fields
|
|
|
|
Every rail declaration must publish:
|
|
|
|
- `contract_version`
|
|
- `composition_kind`
|
|
- `ownership_repo`
|
|
- `execution_architecture`
|
|
- `required_substrate_capabilities`
|
|
- `supported_rollout_modes`
|
|
- `readiness_state`
|
|
|
|
A derived rail must additionally publish:
|
|
|
|
- `base_rail`
|
|
- `base_rail_contract`
|
|
- `inherited_semantics`
|
|
- `overridden_semantics`
|
|
- `compatibility_constraints`
|
|
|
|
## Inheritance Rule
|
|
|
|
A derived rail inherits, rather than copies:
|
|
|
|
- workload identity and ownership metadata
|
|
- common criticality and approval semantics
|
|
- health, evidence, promotion, and rollback vocabulary
|
|
- common dependency and secret-reference representation
|
|
- common audit and conformance requirements
|
|
|
|
A derived rail may override only semantics intrinsic to its execution model.
|
|
For `rail-knative`, those are:
|
|
|
|
- revisions
|
|
- request activation and buffering
|
|
- scale-to-zero and minimum scale
|
|
- concurrency and autoscaling
|
|
- traffic splitting between revisions
|
|
- cold-start readiness and timeout behavior
|
|
- Knative-specific rollback
|
|
|
|
## Non-Goals For `rail-knative`
|
|
|
|
`rail-knative` must not own:
|
|
|
|
- Kubernetes or k3s bootstrap
|
|
- Knative operator installation or cluster-scoped lifecycle
|
|
- generic namespace, RBAC, ingress-controller, certificate, storage, or
|
|
observability ownership
|
|
- Qonto-specific manifests, policies, secret paths, or health checks
|
|
- a fork of the generic Railiance promotion vocabulary
|
|
|
|
## Rail-Neutral Workload Contract
|
|
|
|
Managed workload declarations have a common section and one or more rail
|
|
bindings.
|
|
|
|
The common section owns:
|
|
|
|
- workload and ownership identity
|
|
- criticality and data classification
|
|
- dependencies
|
|
- workload identity and secret references
|
|
- health, smoke, audit, recovery, and approval requirements
|
|
- reliability objectives
|
|
|
|
Each rail binding owns:
|
|
|
|
- rail and contract version constraint
|
|
- rail-specific deployment artifacts
|
|
- scaling, routing, rollout, and rollback parameters
|
|
- required substrate capabilities
|
|
|
|
This makes Kubernetes the default binding while allowing a workload such as
|
|
Qonto to add a justified Knative binding without changing domain ownership.
|
|
|
|
## Compatibility And Readiness
|
|
|
|
Declarations distinguish:
|
|
|
|
- `declared`: source-controlled contract exists
|
|
- `installed`: required runtime components are present
|
|
- `verified`: conformance and smoke evidence passes
|
|
- `production-approved`: criticality-specific admission gates pass
|
|
- `deprecated`: no new bindings are accepted
|
|
|
|
Fabric relations describe topology, not readiness. A `hosts_rail` or
|
|
`binds_rapp` edge must carry or resolve a readiness state before automation
|
|
may treat it as deployable.
|
|
|
|
## Automation Requirement
|
|
|
|
All deterministic checks should be function-executable and idempotent:
|
|
|
|
- schema validation
|
|
- base-rail compatibility resolution
|
|
- substrate-capability matching
|
|
- binding and ownership integrity
|
|
- readiness evidence freshness
|
|
- drift detection
|
|
|
|
Human interaction is reserved for policy acceptance, exceptional risk, or
|
|
authority that cannot safely be delegated. Repeated evidence collection,
|
|
credential routing, reconciliation, and deployment verification should move
|
|
from human operation to agentic interaction and then to functional automation
|
|
as the contract stabilizes.
|