Establish Railiance Fabric graph model

INTENT.md

@@ -0,0 +1,232 @@
+# Railiance Fabric Intent
+
+Date: 2026-05-17
+
+## Intent
+
+Railiance Fabric exists to make the Railiance ecosystem understandable,
+discoverable, and evolvable as services begin to depend on one another.
+
+It models the living fabric of repositories, services, capabilities,
+interfaces, and dependencies so humans and agents can answer questions like:
+
+- Which service provides runtime secrets?
+- Which repos consume the NetKingdom IAM Profile?
+- What breaks if the flex-auth decision envelope changes?
+- Which workloads require OpenBao KV, dynamic database credentials, or
+  object-storage credential vending?
+- Which dependencies are declared, missing, stale, or boundary-violating?
+
+The core idea is simple:
+
+```text
+repo -> service -> capability -> interface -> dependency
+```
+
+Repos remain the source of truth for what they provide and require. Railiance
+Fabric gives those declarations a shared schema, validation model, graph view,
+and discovery surface.
+
+## Why This Exists
+
+Railiance is entering the phase where platform services, identity services,
+application workloads, automation, policy engines, storage, and observability
+will interact continuously.
+
+Without an explicit ecosystem graph, those interactions become folklore:
+implicit dependencies, stale mental maps, fragile deployment order, and unclear
+ownership when interfaces change.
+
+Railiance Fabric turns that implicit web into a reviewable graph:
+
+- capabilities are discoverable by name and semantics
+- interfaces are typed and versioned
+- consumers declare their requirements
+- providers declare what they actually offer
+- State Hub can ingest the graph as a read model
+- agents can reason about blast radius, missing providers, and safe sequencing
+
+## Responsibility Boundary
+
+### Repositories Own Declarations
+
+Each repo owns file-backed declarations for its provided capabilities,
+consumed capabilities, services, and interface contracts.
+
+Examples:
+
+```text
+fabric/capabilities/*.yaml
+fabric/dependencies/*.yaml
+fabric/interfaces/*.yaml
+fabric/services/*.yaml
+```
+
+These files are reviewable, versioned with the repo, and changed through normal
+pull-request or workplan flow.
+
+### Railiance Fabric Owns The Graph Model
+
+Railiance Fabric owns:
+
+- declaration schemas
+- validation rules
+- graph construction
+- local inspection tools
+- provider/consumer matching
+- compatibility and drift checks
+- example declarations for core Railiance services
+- export formats for State Hub, docs, and dashboards
+
+### State Hub Owns The Read Model
+
+State Hub should ingest the ecosystem graph and expose it for coordination,
+but it should not become the primary authoring surface for capability and
+dependency declarations.
+
+This keeps ADR-001 intact: formal work and declarations originate in repos;
+the hub reads, visualizes, and coordinates.
+
+## First-Class Concepts
+
+### Repository
+
+A source-controlled project with ownership, workplans, implementation, and
+local declarations.
+
+### Service
+
+A deployable or callable unit produced by a repository. A repo may produce zero
+or more services.
+
+Examples: OpenBao, key-cape, flex-auth API, Topaz deployment, artifact-store.
+
+### Capability
+
+A stable semantic ability that consumers can depend on without hard-coding the
+current implementation.
+
+Examples:
+
+- runtime secrets
+- IAM Profile issuer
+- authorization decision service
+- PostgreSQL database service
+- object-storage credential vending
+- scope generation
+
+### Interface
+
+The concrete contract through which a capability is consumed.
+
+Examples:
+
+- HTTP API
+- OIDC discovery
+- Kubernetes Secret
+- Kubernetes CRD
+- Helm release
+- CLI
+- database connection
+- object-storage bucket
+- event stream
+- policy package
+- OpenBao KV v2 mount
+- OpenBao database dynamic credential role
+
+### Dependency
+
+A consumer's declared requirement for a capability or interface, including
+version, environment, auth, data classification, criticality, and fallback
+expectations.
+
+### Binding
+
+A resolved edge between a consumer dependency and a provider capability.
+Bindings may be exact, compatible, degraded, missing, or disputed.
+
+## Design Principles
+
+- Source of truth lives in repos.
+- Capabilities are stable; implementations may move.
+- Interfaces are typed, versioned, and testable.
+- Dependencies are explicit requirements, not accidental imports.
+- Discovery is graph search, not tribal memory.
+- Validation should catch missing providers before deployment time.
+- Compatibility should be machine-checkable where possible.
+- Human-readable files matter; agents and humans must both be able to inspect
+  declarations without a running service.
+- The model must support partial adoption. A repo can begin with one declared
+  capability or dependency and mature over time.
+- The graph should reveal boundary violations without pretending to own every
+  domain's decisions.
+
+## Strategic Role
+
+Railiance Fabric sits between repository scoping, State Hub, and the Railiance
+deployment stack.
+
+```text
+repo-local declarations
+        |
+        v
+Railiance Fabric schema and graph tools
+        |
+        +-- State Hub ingestion and coordination
+        +-- documentation and topology maps
+        +-- agent planning and blast-radius analysis
+        +-- deployment readiness checks
+```
+
+It complements:
+
+- `repo-scoping`, which explains what a repo is useful for.
+- `the-custodian/state-hub`, which coordinates domains, workstreams, tasks, and
+  progress.
+- `railiance-platform`, which deploys shared S3 services such as OpenBao,
+  PostgreSQL, Valkey, and object storage.
+- `net-kingdom`, which owns identity, credential, and security architecture.
+- `flex-auth`, which owns authorization policy and decision semantics.
+
+## Non-Goals
+
+Railiance Fabric is not:
+
+- a deployment orchestrator
+- a replacement for State Hub
+- a replacement for SCOPE.md
+- a service mesh
+- a CMDB that must manually mirror everything
+- an authorization engine
+- a secret manager
+- a package registry
+
+It may inform those systems, but its job is the ecosystem graph and declaration
+model.
+
+## Early Questions
+
+- What is the smallest declaration schema that is useful without becoming
+  ceremony?
+- Which capability and interface types must exist on day one?
+- How should provider/consumer matching handle environment, version, auth,
+  tenant, and data-class constraints?
+- Which graph checks are advisory, and which should block deployment?
+- How does State Hub ingest the graph without becoming the authoring source?
+- How do we represent capabilities that are planned but not deployed yet?
+
+## Maturity Target
+
+A mature Railiance Fabric should let a human or agent ask:
+
+```text
+Show all consumers of OpenBao.
+Show missing providers for production Railiance.
+Show every service that depends on NetKingdom identity claims.
+Show all interfaces crossing from S3 platform services into S5 applications.
+Show blast radius for changing flex-auth decision envelope v1.
+Show runtime readiness for tenant:coulomb onboarding.
+```
+
+and receive source-linked, repo-owned answers.
+