railiance-master/INTENT.md

layer	role	standard	standard_version	companion
Taxonomy	null	netkingdom-security-layer-model	0.7	net-kingdom/SECURITY-COMPANION.md

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.

Layer: Taxonomy. This is the declaration required by NetKingdom Security Layer Model v0.7 §11 and the working companion v0.2. It is this repository's own voice, not a catalog row about us. railiance-master is not a member of the NetKingdom §4 security-estate catalog. Operations belong to Railiance; NetKingdom provides the security and approval framework those operations consume. The statute is net-kingdom/canon/standards/security-layer-model_v0.7.md; the companion is net-kingdom/SECURITY-COMPANION.md. On disagreement the statute governs, and a disagreement is a finding for gate-house.

---

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. That is why an approval object is a NetKingdom engine concept and never a Railiance axis. 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-*.

NetKingdom Security Layer Model v0.7 §20 restates these definitions; it does not author them. Changes to that boundary require this repository's assent for the axis definitions and glas-harness's assent for the session and tool-policy seam.

---

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 three 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.
• NetKingdom owns the security-layer constitution (security-layer-model v0.7 and its working companion). gate-house authors the layers, the one decision point, and the Staff/Engine/Tooling binding rules. This repository consumes that constitution for how workload operations use identity, authorization, approval, credential, and evidence services. It does not host a second decision point, an approval store, a credential plane, or an evidence archive.
• 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, security-layer constitution, and publication infrastructure are related responsibilities, not one responsibility hidden in four repositories.

---

How Railiance Consumes NetKingdom Security

For any Railiance consumer of NetKingdom security, without exception:

1. Authorization decisions come from access-engine and from nowhere else.
2. Approvals are objects in approval-engine, consumed as claims.
3. Credentials are materialized by secrets-engine after a decision, never as a substitute for one.
4. Evidence goes to audit-core under the bound that an archive proves alteration and truncation after arrival, not omission at source.
5. Anything causing a protected side effect is PEP-shaped and owes a decision record or a recorded unreachable-engine stance, a lifetime on every allow, and a published stance map.

This repository is not PEP-shaped. It defines contracts; it does not cause protected side effects. Implementation rails, rapps, and reefs that do cause them inherit those obligations in their own repositories.

What is not settled, and must not be guessed here: how the four axes map onto Taxonomy, Tooling, Engine, and Staff. A rapp is the most likely resource a decision is about; a rail is where PEP shape is most likely to live, but a rail is a contract and §6.4 obligations attach to repositories; a reef is adjacent to a security zone without being one; the ownership axis is adjacent to the principal a decision is rendered for without being equal to it; and the glas-harness / §3.4 seam is where "tool availability is not permission" is either enforced or lost. Those five questions need explicit decisions with the other side's assent. They are not implied by this file.

Admission (whether a binding may run in production) and exposure (who may reach a listener) remain Railiance axes. They are not authorization decisions.

---

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
• NetKingdom security is consumed through one decision point, never re-implemented as a Railiance convenience
• 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. The security-layer constitution — layers, one decision point, Staff/Engine binding, evidence bounds — comes from NetKingdom. This repo owns the Railiance-specific application: repo-family vocabulary, workload coverage, composition, admission, exposure, the interaction boundary with that security constitution, 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.

13. Consume Security; Do Not Become A Second Decision Point

A registry, schema, cache, or admission rule that resolves whether an actor may act has decided early. Railiance may package, place, admit, and expose workloads. It may not render or cache authorization decisions, mint standing credentials in lieu of a decision, or treat audit silence as non-occurrence.

---

What This Is (Conceptually)

This repository is:

• an architecture-definition home
• Taxonomy of Railiance workload operations — terms, family contracts, and standards for how workloads are owned, executed, packaged, and bound
• 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
• the assenting owner of the axis definitions NetKingdom restates at the operations/security interaction boundary
• a migration map from current repo reality toward cleaner framework structure

---

What This Is Not

This repository is not:

• a member of the NetKingdom §4 security-estate catalog
• an Engine, a PDP, a PIP, an evidence plane, or a credential lifecycle API
• PEP-shaped — it causes no protected side effects
• 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 NetKingdom security-layer constitution owned by gate-house and published as net-kingdom canon
• 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 place to guess how rails, rapps, reefs, and ownership map onto Taxonomy, Tooling, Engine, and Staff

A rein deployed as a managed service is a workload on the four Railiance axes. The harness contract is not this repository's. A mapping of those axes onto the NetKingdom layers is an open interaction-boundary question, not an implied taxonomy.

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-*
• a durable interaction boundary with the NetKingdom security-layer model: consume §20.2; settle §20.3 only by explicit, assented decisions
• machine-readable layer declaration and a total account of non-Tooling clients, without acquiring Engine or PEP permissions by gradual practice
• 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, and without becoming a second security decision point, even as the ecosystem grows from exploratory operation into production-grade responsibility?