railiance-master/docs/rail-composition-contract.md

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:

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.