Date: 2026-07-25 Status: Accepted

## Context

Railiance already has a meaningful set of ownership repos such as `railiance-infra`, `railiance-cluster`, `railiance-platform`, `railiance-enablement`, `railiance-apps`, `railiance-forge`, and `railiance-fabric`.

That structure is useful, but it does not by itself capture all of the dimensions Railiance now needs.

In particular, the architecture needs clear source-controlled homes for:

- workload execution contracts across different operations architectures,
- managed workload packages as first-class repos,
- and concrete substrate boundaries such as named servers, workstations, or grouped environments.

Without that separation, Kubernetes-specific workload semantics remain mixed into `railiance-cluster`, workload wrappers remain mixed into ownership repos, and concrete substrates remain under-described.

Railiance also operates inside a wider ecosystem around Railiance, Net Kingdom, and the Helix Forge software factory. That wider context needs architecture that can support both exploratory operation and production-grade evolution without leaving key responsibilities ambiguous.

## Decision

Railiance adopts four canonical repository families:

1. `railiance-*` for ownership and responsibility areas
2. `rail-*` for workload execution contracts
3. `rapp-*` for Railiance-managed workload packages
4. `reef-*` for durable substrate boundaries

The current implementation wave is explicitly centered on `rail-kubernetes` as the default base rail. Additional rails are introduced only when a concrete workload has a sound reason to run on a distinct execution architecture.

`rail-knative` is the first expected follow-on rail, motivated by the need to support `qonto-assistent`, but it should follow the `rail-kubernetes` boundary cleanup rather than bypass it.

## Meaning Of Each Family

### `railiance-*`

Owns major architectural responsibilities, shared policies, and durable layer boundaries.

### `rail-*`

Owns how workloads run on a specific execution architecture such as Kubernetes, Knative, KEDA, Fission, or Nuclio.

In the current phase, `rail-kubernetes` is the default path for platform services and managed applications.

### `rapp-*`

Owns the managed workload package for one service or application, whether it is an internal workload or a wrapped upstream product.

Its role is to provide the managed wrapper and scaffolding needed to run that workload in the Railiance and Net Kingdom context. It does not replace responsibility ownership.

### `reef-*`

Owns the concrete substrate reality where rails and `rapp`s are bound, such as a named server, cluster, workstation, or grouped substrate class.

A reef is about purpose-bound compute resources, not merely about individual machines.

## Consequences

### Positive

- Ownership, execution, workload identity, and substrate identity become separate concerns.
- Railiance can support multiple execution architectures without forcing all workload semantics into `railiance-cluster`.
- Platform services and applications can both become first-class managed workload packages where appropriate.
- Concrete substrates gain a clear architectural home without overloading the ownership repos.
- The framework gains a disciplined default path for introducing new rails instead of proliferating them speculatively.

### Required Follow-On Work

- Define the initial `rail-*` contracts, starting with `rail-kubernetes`.
- Evolve the current `railiance/app.toml` and overlay pattern into a rail-aware, eventually rail-neutral workload packaging contract.
- Identify which current workloads should become `rapp-*` repos.
- Extend `railiance-fabric` so rails, `rapp`s, and reefs become graph-native.
- Define when mixed-rail reefs are acceptable and when clearer substrate separation should be preferred.

### Constraints

- `reef-*` must not become a default one-repo-per-machine pattern.
- Generic logic stays in the appropriate ownership repo.
- A named machine gets its own reef only when that machine is itself a durable substrate boundary.
- `rapp-*` repos must not become shadow ownership repos.
- Transitional substrate labels should not be canonized before the pattern is operationally stable.

## Current Interpretation For Existing Repos

- `railiance-*` repos remain the primary ownership axis.
- Current workload-execution logic in `railiance-cluster` is a candidate to migrate into `rail-kubernetes`.
- Current workload wrappers inside `railiance-apps`, `railiance-platform`, or `railiance-forge` may evolve into `rapp-*` repos over time.
- Current named substrates such as COULOMBCORE, RAILIANCE01, and WORKSTATION may justify `reef-*` repos when they represent real operational boundaries.
- A reef may host more than one rail in early or mixed environments, but production-critical substrates should prefer clearer purpose and primary-rail boundaries unless a mixed design is justified.

## Notes

This ADR defines the repository taxonomy. It does not yet mandate a full migration or rename of existing repos. Migration should happen when it produces clearer ownership and lower ambiguity, not merely for naming purity.