Establish Railiance architecture home

docs/adr/ADR-0001-repository-prefix-architecture.md

@@ -0,0 +1,133 @@
+# ADR-0001: Repository Prefix Architecture
+
+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.