22d88db056
State that Railiance organizes workload operations along the four repo axes, and that glas-harness reins are adjacent rather than a fifth family. Keep the ADR-0007 coverage fact in SCOPE so intent stays aspirational. Assistant: grok Assistant-Session: 01a04c9f-cd6b-7741-bce0-f1d9d1b3c3bc
285 lines
11 KiB
Markdown
285 lines
11 KiB
Markdown
# INTENT
|
|
|
|
> This file captures **why this repository exists**,
|
|
> the **direction it is moving toward**, and
|
|
> the **kind of system it is meant to become**.
|
|
> It is intentionally **aspirational and stable**, not a description of current implementation.
|
|
|
|
---
|
|
|
|
## One-liner
|
|
|
|
**The authoritative source for Railiance framework architecture — turning
|
|
evolving repo families, workload models, and substrate realities into coherent,
|
|
reviewable, and permanently publishable boundary decisions.**
|
|
|
|
Railiance itself is a systematic way to organize the **operation of
|
|
workloads**: who owns them, how they run, how they are packaged, and where
|
|
they are bound. This repository exists to keep that language canonical.
|
|
|
|
---
|
|
|
|
## Why This Exists
|
|
|
|
As Railiance grows, implementation repos naturally solve immediate problems:
|
|
infrastructure, cluster runtime, platform services, forge operations,
|
|
application releases, and ecosystem modeling.
|
|
|
|
What those repos cannot safely do on their own is define the framework's shared
|
|
meaning.
|
|
|
|
Without a canonical architecture home:
|
|
|
|
* the same terms drift across repos,
|
|
* new repo families appear without clear boundaries,
|
|
* execution models and workload wrappers get mixed into the wrong layers,
|
|
* and migrations happen by local habit rather than deliberate framework design.
|
|
|
|
This repository exists to define the **shared architectural language** of
|
|
Railiance before that language hardens accidentally inside implementation repos.
|
|
|
|
---
|
|
|
|
## What The Framework Organizes
|
|
|
|
Railiance organizes **workload operations**, not merely repositories.
|
|
|
|
A **workload**, in the Railiance-specific sense, is a managed running
|
|
deployable. Human commands, credential patterns, broker actions, approvals,
|
|
and infrastructure resources that are not themselves deployables are not
|
|
workloads. InfoTechCanon supplies the general landscape vocabulary; this
|
|
framework owns the Railiance application: every such workload is operated
|
|
through four composable axes.
|
|
|
|
| Prefix | Axis | Question |
|
|
| --- | --- | --- |
|
|
| `railiance-*` | ownership | Who owns this capability? |
|
|
| `rail-*` | execution contract | How does this workload run? |
|
|
| `rapp-*` | managed package | What exactly is being packaged and operated? |
|
|
| `reef-*` | substrate | Where is it bound, and as what operational reality? |
|
|
|
|
Those families are complementary answers about one workload. They are not
|
|
competing repo types. The detailed model, creation rules, and composition
|
|
semantics live in `docs/repository-axes.md` and the accepted framework ADRs.
|
|
The coverage rule — what is and is not a workload — belongs to the rapp
|
|
declaration contract; this file names the object of the architecture.
|
|
|
|
**Adjacent, not a fifth axis.** `rein-*` repos are glas-harness agent harness
|
|
backends. Their name was chosen to echo `rail-*`; that echo is analogical,
|
|
not taxonomic. Agentic session semantics — session loops, tool policy,
|
|
harness routing, and model selection — belong to glas-harness and its reins.
|
|
This repository does not define a `rein-*` family. When a rein is installed
|
|
and operated as a managed service, it is a workload like any other and is
|
|
packaged, executed, and bound through `rapp-*`, `rail-*`, and `reef-*`.
|
|
|
|
---
|
|
|
|
## Operating Context
|
|
|
|
Railiance does not exist in isolation.
|
|
|
|
It is part of a wider, coevolving ecosystem around **Railiance**, **Net
|
|
Kingdom**, and the **Helix Forge** software factory. That ecosystem is
|
|
intended to support the full path from:
|
|
|
|
* product ideation,
|
|
* discovery,
|
|
* delivery,
|
|
* operation,
|
|
* marketing,
|
|
* and monetization.
|
|
|
|
The architecture therefore has to work across experimental and production-grade
|
|
realities at the same time.
|
|
|
|
That matters because repo boundaries in Railiance are not only about code
|
|
organization. They shape how humans and agents coordinate responsibilities,
|
|
reason about workload placement, and evolve operating models without losing the
|
|
ability to scale into more mature security and delivery expectations.
|
|
|
|
Railiance also participates in two wider governance structures:
|
|
|
|
* **InfoTechCanon** owns the general semantic models, standards, and repository
|
|
conventions that Railiance adopts. This repository imports those concepts and
|
|
applies them to Railiance; it does not redefine the canon by local usage.
|
|
* **`policy-nexus`** owns permanent publication, addressing, history, and
|
|
currency for estate policy. This repository remains the source and
|
|
ratification home for its architecture decision records. Publication is
|
|
generated downstream and never written back here.
|
|
|
|
That separation matters. Content authority, semantic canon, and publication
|
|
infrastructure are related responsibilities, not one responsibility hidden in
|
|
three repositories.
|
|
|
|
---
|
|
|
|
## The Mission
|
|
|
|
> *Where we are going.*
|
|
|
|
To become the **canonical home for Railiance framework architecture** —
|
|
where the language of workload operations, repository taxonomy, architectural
|
|
boundaries, execution-model concepts, managed packaging, substrate concepts,
|
|
and migration direction is defined once, reviewed here, published durably when
|
|
governing, and referenced everywhere else.
|
|
|
|
This means:
|
|
|
|
* Railiance vocabulary is defined through **explicit architectural documents**
|
|
* New repo families and framework terms are introduced through **clear decisions**
|
|
* Ownership, execution mode, workload identity, and substrate identity remain
|
|
**separate and composable**
|
|
* Adjacent families such as glas-harness `rein-*` remain **named and bounded**,
|
|
not absorbed as extra Railiance axes
|
|
* Explorations mature into **stable decisions** before they spread across the
|
|
wider repo landscape
|
|
* Governing ADRs carry enough ownership, revision, status, and review metadata
|
|
to be published without a second source of truth
|
|
* The framework can support both **early-stage experimentation** and
|
|
**production-grade operation** without collapsing those needs into one vague
|
|
structure
|
|
|
|
---
|
|
|
|
## Core Principles
|
|
|
|
### 1. Architecture Before Proliferation
|
|
|
|
New repo patterns should be named and bounded deliberately before they multiply
|
|
across the ecosystem.
|
|
|
|
### 2. Shared Vocabulary Is Infrastructure
|
|
|
|
Terms such as `railiance-*`, `rail-*`, `rapp-*`, and `reef-*` are not cosmetic.
|
|
They are the vocabulary of workload operations. They shape ownership, tooling,
|
|
and operator understanding.
|
|
|
|
### 3. Separate Axes Cleanly
|
|
|
|
Ownership, execution architecture, workload packaging, and substrate reality
|
|
must not collapse into one ambiguous repo type.
|
|
|
|
### 4. Decisions Need A Canonical Home
|
|
|
|
Framework-level architecture decisions should live in one source-controlled
|
|
place rather than being reconstructed from scattered repo-local assumptions.
|
|
|
|
### 5. Stable Meaning, Evolvable Model
|
|
|
|
The framework vocabulary should stay understandable over time even as specific
|
|
rails, workloads, and substrates evolve.
|
|
|
|
### 6. Guide Implementation, Do Not Shadow It
|
|
|
|
This repo should define structure and direction, not absorb the operational
|
|
content that belongs in the implementation repos themselves.
|
|
|
|
### 7. Stabilize The Default Path First
|
|
|
|
Railiance should not introduce multiple top-level rails speculatively.
|
|
|
|
The default path for platform services and managed applications is
|
|
`rail-kubernetes` until there is a concrete workload need and a sound argument
|
|
for a distinct rail.
|
|
|
|
### 8. Managed Packaging Is Not Ownership
|
|
|
|
`rapp-*` repos exist to wrap third-party or self-built workloads so they can be
|
|
run as fully managed Railiance workloads in the wider Railiance and Net Kingdom
|
|
context.
|
|
|
|
They do not replace the ownership repos that define why a capability exists.
|
|
|
|
### 9. Substrates Need Purpose, Not Just Names
|
|
|
|
`reef-*` repos should represent compute resources organized around a defined
|
|
purpose and operational boundary.
|
|
|
|
They should not be created merely because a named machine exists.
|
|
|
|
### 10. Import Canon; Own Railiance Semantics
|
|
|
|
General concepts such as intent, scope, demand, task, governance, evidence,
|
|
repository layout, and workload come from InfoTechCanon and estate conventions.
|
|
This repo owns their Railiance-specific application: repo-family vocabulary,
|
|
workload coverage, composition, admission, exposure, and cross-repo boundary
|
|
decisions.
|
|
|
|
### 11. Author Here; Publish Downstream
|
|
|
|
Accepted framework ADRs are policy sources. They are authored, reviewed,
|
|
superseded, or withdrawn here and published by `policy-nexus`. Workplans,
|
|
evidence, runbooks, and general documentation remain working material rather
|
|
than becoming policy merely because they are useful.
|
|
|
|
### 12. Keep Intent, Scope, and Demand Distinct
|
|
|
|
`INTENT.md` describes the direction and stable purpose. `SCOPE.md` describes
|
|
what the repository currently owns and achieves. Consumer requests and incoming
|
|
proposals are demand signals until reviewed; they do not silently expand scope
|
|
or become committed work.
|
|
|
|
---
|
|
|
|
## What This Is (Conceptually)
|
|
|
|
This repository is:
|
|
|
|
* an **architecture-definition home**
|
|
* a **repository taxonomy authority**
|
|
* a home for **framework-level ADRs and conceptual models**
|
|
* the **source repository** for Railiance framework ADRs published through
|
|
`policy-nexus`
|
|
* a place to define how **workload operations compose** across ownership, rail,
|
|
rapp, and reef
|
|
* a **migration map** from current repo reality toward cleaner framework
|
|
structure
|
|
|
|
---
|
|
|
|
## What This Is Not
|
|
|
|
This repository is not:
|
|
|
|
* the infrastructure substrate
|
|
* the Kubernetes runtime or workload execution layer
|
|
* the shared platform-services layer
|
|
* the forge runtime
|
|
* the application release surface
|
|
* the implementation of the ecosystem graph registry
|
|
* the general semantic canon owned by InfoTechCanon
|
|
* the permanent policy publication surface owned by `policy-nexus`
|
|
* a policy CMS or a second copy of published policy
|
|
* a dumping ground for operational runbooks that belong elsewhere
|
|
* the glas-harness `rein-*` family, or the owner of agentic session semantics
|
|
* a place to invent a fifth repository family for LLM or agentic work
|
|
|
|
A rein deployed as a managed service is a workload on the four Railiance axes.
|
|
The harness contract is not this repository's.
|
|
|
|
It is the **place where the framework explains itself**.
|
|
|
|
---
|
|
|
|
## Direction of Evolution
|
|
|
|
This repository is expected to evolve toward:
|
|
|
|
* clearer **repository-family definitions** and lifecycle rules
|
|
* stable **rail**, **rapp**, and **reef** contracts
|
|
* stronger **boundary guidance** for new repos and migrations
|
|
* a durable distinction between Railiance workload axes and adjacent harness
|
|
families such as `rein-*`
|
|
* better linkage between architecture decisions and `railiance-fabric`
|
|
declarations
|
|
* publication-ready ADR lifecycle metadata and durable downstream policy links
|
|
* explicit, graded adoption of the InfoTechCanon repository-layout convention
|
|
* a repeatable path from **exploration -> ADR -> adopted framework pattern**
|
|
* a clear model for when experimental multi-rail substrates are acceptable and
|
|
when production-grade separation is the better default
|
|
|
|
---
|
|
|
|
## Guiding Question
|
|
|
|
> **How can Railiance organize the operation of workloads clearly enough that every new ownership boundary, rail, managed package, and substrate increases capability without increasing ambiguity, even as the ecosystem grows from exploratory operation into production-grade responsibility?**
|