railiance-master/SCOPE.md

SCOPE

This file describes the repository's current, evidenced responsibility. It is deliberately distinct from the direction in INTENT.md and from unreviewed consumer demand.

---

One-liner

Current source of truth for Railiance repository taxonomy, family contracts, framework ADRs, declaration schemas, and cross-repo architecture workplans.

---

Current Responsibility

railiance-master currently owns the Railiance-specific meaning of the four repository axes: ownership repos (railiance-*), execution contracts (rail-*), managed workload packages (rapp-*), and substrate boundaries (reef-*). Workload, in that Railiance-specific sense, is a managed running deployable under rapp coverage (ADR-0007); human acts, credentials, broker actions, and non-deployable infrastructure resources remain outside that meaning.

This repository declares itself Taxonomy of Railiance workload operations in INTENT.md frontmatter and layer.yaml (layer: Taxonomy, NetKingdom security-layer-model v0.7). It is not a row in the NetKingdom §4 catalog. It is not PEP-shaped. Assent to statute §20 is docs/adr/ADR-0009-netkingdom-security-layer-interaction.md.

The current implementation includes:

• nine accepted framework ADRs covering repository families, rail composition, production admission, the rapp declaration contract, exposure posture, and the NetKingdom security-layer interaction boundary;
• framework contracts and migration guidance under docs/;
• JSON Schemas for rail, rapp, and reef declarations plus a family-declaration validator and fixtures;
• cross-repo workplans and State Hub bindings for architecture changes that do not belong wholly to one implementation repository.

This repo owns the architectural source documents and their lifecycle. It does not own every implementation implied by them.

---

In Scope

• Railiance framework architecture and Railiance-specific vocabulary
• Repository taxonomy, naming, composition, lifecycle, and boundary rules
• Architecture decisions affecting multiple Railiance repositories
• Rail/rapp/reef declaration contracts and framework-level validation rules
• Cross-repo workplans whose outcome cannot be owned cleanly by one concrete ownership or family repository
• Source metadata and lifecycle decisions for this repo's publishable ADRs
• Routing accepted architecture into repo-local implementation work
• Declaring this repository's NetKingdom security layer and the operations side of the Railiance/NetKingdom interaction boundary
• Framework-level consumption rules for how rails, rapps, and reefs use access-engine, approval-engine, secrets-engine, and audit-core without hosting those engines here

---

Out of Scope

• General semantic canon or repository standards owned by info-tech-canon
• Permanent policy addressing, rendering, hosting, and currency checks owned by policy-nexus
• Regulatory interpretation or disclosure timing owned by risk-nexus
• OS provisioning and host hardening owned by railiance-infra
• Kubernetes substrate implementation owned by railiance-cluster
• Rail implementation owned by the relevant rail-* repository
• Managed workload implementation owned by the relevant rapp-* repository
• Reef-local substrate declarations and operations owned by the relevant reef-* repository
• Platform services, application releases, forge runtime, and Fabric graph implementation owned by their concrete repositories
• glas-harness rein-* harness contracts and agentic session semantics; a deployed rein is a workload on the four axes, not a fifth Railiance family
• The NetKingdom security-layer constitution owned by gate-house and published as net-kingdom canon
• Authorization decisions (access-engine), approval objects (approval-engine), credential materialization (secrets-engine), and evidence custody (audit-core)
• PEP stance maps and unreachable-engine behaviour of implementation repositories; this repo is not PEP-shaped
• A guessed mapping of rail, rapp, reef, or ownership onto Taxonomy, Tooling, Engine, or Staff — statute §20.3 is tracked unanswered in docs/netkingdom-axis-layer-open-questions.md
• Automatic containment or production observation; both are estate-wide zeros, not this repository's gaps to close

---

Authority and Publication Boundaries

Concern	Authority	Relationship to railiance-master
General semantic models and repository-layout standard	info-tech-canon	Imported and applied; not redefined here
Security-layer constitution (layers, one PDP, Staff/Engine binding, evidence bounds)	gate-house / net-kingdom canon, security-layer-model v0.7	Imported as the consumption constitution; not redefined here
Workload-operation axes and coverage	railiance-master	Owned here; restated, not authored, by NetKingdom §20
Railiance framework architecture and ADR lifecycle	railiance-master	Authored, reviewed, accepted, superseded, or withdrawn here
Permanent publication of accepted ADRs	policy-nexus	Downstream read-only publication; never a second source of truth
Work indexing and coordination	State Hub	Cache/index rebuilt from repo-local workplan files; a non-catalogued client, not a Tooling contact
Runtime implementation	Concrete ownership, rail, rapp, or reef repo	Routed outward after the framework boundary is settled
Agentic session and tool-policy seam	glas-harness	Adjacent; joint assent required for §20 changes that touch the seam

The policy publication corpus from this repo is docs/adr/*.md. Workplans, evidence, runbooks, schemas, and general documentation are not policy merely because they are useful. policy-nexus currently discovers the earlier eight ADRs as metadata-pending; ADR-0009 is an additional source record awaiting the same publication addressing.

---

Relevant When

• Defining or changing a Railiance repository family or framework term
• Clarifying a boundary shared by multiple implementation repositories
• Deciding how rails, rapps, reefs, and ownership repositories compose
• Establishing framework-wide admission, exposure, declaration, or lifecycle rules
• Planning a migration that spans multiple Railiance repositories
• Recording or reviewing a Railiance framework ADR
• Declaring or changing this repository's security layer, or the operations side of the NetKingdom interaction boundary

Not Relevant When

• Work belongs entirely inside one implementation repository
• Work is operational execution of an already-settled boundary
• A workload-specific decision has no framework-wide consequence
• The request is about glas-harness session, tool, or rein-backend semantics rather than how a deployed rein is packaged, executed, or bound as a workload
• The request is to render an authorization decision, store an approval, mint a credential, or keep an evidence archive
• The request assumes observation-in-production or automatic containment exists
• The request is raw demand that has not yet been reviewed for purpose and scope fit

---

Current State

• Status: maintained and evolving
• Architecture baseline: four repository axes are materialized and governed by accepted ADRs and contracts
• Layer declaration: INTENT.md frontmatter and layer.yaml declare layer: Taxonomy against security-layer-model v0.7; no Tooling contacts; State Hub listed as a non-Tooling client; not PEP-shaped
• Security consumption: ADR-0009 and docs/netkingdom-security-consumption-contract.md encode the §20.2 rules (one PDP, approvals as claims, credentials after a decision, evidence bound, PEP-shape of implementation runtimes)
• Admission (ADR-0006), exposure (ADR-0008), and authorization (access-engine via ADR-0009) are demarcated in-repo
• Axis-to-layer mapping: five statute §20.3 questions are tracked unanswered in docs/netkingdom-axis-layer-open-questions.md; next review 2026-11-29
• Validation: rail/rapp/reef schemas and declaration checks are implemented
• Active cross-repo work: OpenBao migration closeout remains partially blocked; public-listener retraction is in progress while destructive source cleanup retains separate approval and disaster-recovery gates
• Publication: ADR discovery exists in policy-nexus; publication metadata and stable addressing remain an open alignment gap, now including ADR-0009

---

InfoTechCanon Repository-Layout Alignment

Declared conformance: core under ITC-REPO-LAYOUT 0.1.0-RC1.

• INTENT.md contains stable aspiration and boundaries.
• SCOPE.md contains current evidenced responsibility and explicit gaps.
• demand/ holds unreviewed architecture demand and requires a purpose/scope disposition before work is committed.
• docs/ contains stakeholder-facing framework contracts and ADRs.
• workplans/ contains committed work and remains authoritative for State Hub.
• history/ contains dated, inactive architecture explorations.

Intentional deviations and omissions:

• Finished workplan archival follows the Custodian ADR-001 convention at workplans/archived/YYMMDD-..., not the generic ITC history/ placement, so State Hub discovery remains deterministic.
• research/, spec/, wiki/, and issues/ are not currently claimed. They should be added only when their distinct semantics are needed, not as empty structural decoration.
• Consumer purposes and inbound requests are not folded into INTENT or SCOPE; demand/ provides that third plane and resolved reviews move to dated history/ records.

---

How It Fits

• Upstream standards: info-tech-canon, the-custodian canon, Custodian workplan conventions, NetKingdom security-layer-model v0.7 and SECURITY-COMPANION.md v0.2 (consumption constitution, not authored here)
• Downstream policy publisher: policy-nexus (ADRs only, read-only)
• Downstream architecture consumers: all railiance-*, rail-*, rapp-*, and reef-* repositories
• Coordination/index: State Hub
• Common collaborators: railiance-fabric, railiance-platform, railiance-cluster, railiance-infra, railiance-enablement

---

Getting Oriented

• Start with: README.md, INTENT.md, SCOPE.md
• Architecture entry points: docs/repository-axes.md, docs/reef-substrate-model.md, docs/adr/
• NetKingdom interaction: layer.yaml, docs/netkingdom-security-consumption-contract.md, docs/netkingdom-axis-layer-open-questions.md, docs/adr/ADR-0009-netkingdom-security-layer-interaction.md
• NetKingdom alignment review: history/260829-demand-netkingdom-security-layer-alignment.md
• Machine-readable contracts: schemas/, layer.yaml, tools/validate-family-declarations.py
• Active and historical coordination: workplans/, WORK-RECORDS.md

---

Provided Capabilities

type: documentation
title: Railiance repository taxonomy
description: Defines the canonical Railiance repo families and how ownership repos, rails, managed workloads, and substrate boundaries compose.
keywords: [railiance, architecture, taxonomy, rail, rapp, reef]

type: governance
title: Railiance framework architecture decisions
description: Owns framework ADR content and lifecycle while permanent publication is delegated read-only to policy-nexus.
keywords: [architecture, adr, governance, boundaries, policy-source]

type: validation
title: Railiance family declaration contracts
description: Provides schemas and validation rules for rail, rapp, and reef declarations and their cross-family constraints.
keywords: [schema, validation, declaration, rail, rapp, reef]

---

Gap to Intent

The remaining alignment work is to complete downstream ADR publication (including ADR-0009), cleanly archive completed work without breaking State Hub conventions, and retain a repeatable canon-consumer review packet as the architecture evolves. The NetKingdom security-layer declaration, §20 assent, consumption contract, and admission/exposure/authorization split are now evidenced. The five axis-to-layer questions remain tracked unanswered until their named reviewers assent; they are not a silent deficit of this repository. Do not invent the mapping, host a PDP, or take PEP shape here.