railiance-fabric/docs/FabricDiscoveryAndUpdate.md

# Fabric Discovery And Update

## Intent

`railiance-fabric` models the durable infrastructure-responsibility graph of the
Railiance netkingdom.

A fabric is not a repository, environment, cluster, deployment scenario, or
security zone. A fabric is the financial and operational responsibility boundary
around infrastructure: who pays for it, who is accountable for it, and who has
the authority to keep it alive.

The graph exists to answer:

- what infrastructure, services, repositories, deployables, endpoints, and
  machines exist;
- who owns or pays for each node;
- which fabrics and subfabrics contain those nodes;
- which durable interfaces cross ownership boundaries;
- which cross-boundary interfaces provide utility that may carry business value.

Fabric intentionally stays out of live operational telemetry. It may represent
that a service, host, endpoint, or deployment exists because durable automation
or configuration proves it. It should not represent whether that thing is
currently healthy, loaded, failing, or profitable in the accounting sense.

## Financial Boundary Terms

Fabric uses financial responsibility terms for fabric boundaries.

### King

The king is responsible for the whole netkingdom.

The king has the key to the netkingdom. Literally, this means the master key or
at least a relevant key component for secrets, backups, and recovery paths across
the infrastructure under the netkingdom.

The king also holds the legal and contractual relationship with all lords and
tenants. Even when responsibility is delegated, the king remains the actor that
can ultimately restore, recover, govern, or terminate the netkingdom.

### Lord

A lord pays for a fabric.

A lord is accountable for a durable infrastructure-responsibility boundary. In
the current Railiance setup there is one effective fabric because one actor pays
for all infrastructure. Additional fabrics appear when the responsibility to pay
for a coherent infrastructure boundary changes.

### Tenant

A tenant pays for restricted use of a subfabric.

A tenant is not the root payer for the whole fabric. A tenant receives bounded
access to utility inside a subfabric and may consume services or interfaces
provided by a lord, by the king, or by another tenant-facing utility.

## Fabrics, Subfabrics, And Views

### Fabric

A fabric is a durable responsibility boundary. Membership changes when financial
or operational responsibility changes, not when a service is redeployed, a repo
is refactored, a host is replaced, or an environment name changes.

Criteria for establishing a fabric:

- there is a lord who pays for the infrastructure in that boundary;
- the boundary can be discovered from durable infrastructure, deployment, or
  contractual evidence;
- the boundary remains stable across ordinary deployment and development churn;
- ownership changes imply a meaningful change to who is accountable for cost,
  continuity, recovery, and utility delivery.

### Subfabric

A subfabric is a delegated responsibility or tenancy partition within a fabric.

Subfabrics are useful when a tenant receives restricted access to infrastructure
or utility while the parent fabric remains under a lord or king. A subfabric may
eventually become a separate fabric if payment, control, recovery, and legal
responsibility move to another lord.

### View

A view is a diagnostic or informational slice through the graph.

Views can filter by repository, service, environment, machine, endpoint, tenant,
workstream, deployment stack, or business capability. Views do not define fabric
membership and should not mutate fabric boundaries.

Zone views are a special kind of view. They group the subgraph by deployment
environment, deployment scenario, routing authority, or access zone. They are
useful for questions such as:

- which services are currently visible in private dev, shared test, or
  production;
- which control surfaces appear in user-facing zones;
- which production surfaces still have unrestricted developer access;
- which routes exist in production but not in test;
- which early-access interfaces lack an explicit policy authority.

### Environment

An environment such as local, dev, staging, production, or lab is a deployment
classification inside a fabric. It is not a fabric by itself.

Railiance uses these baseline environment terms:

| Environment | Meaning |
|-------------|---------|
| `dev` | Private developer-local execution. Useful for debugging and discovery, but not shared truth for other developers unless explicitly published. |
| `test` | Shared central test stage for collaborators and friendly early-access users. |
| `prod` | Production execution. Alpha-stage developer access may exist now, but production must be able to move toward restricted operator access and applicable security and data-privacy controls. |

### Deployment Scenario

A deployment scenario is a realized or planned arrangement of services,
machines, endpoints, automation, and configuration. It belongs inside a fabric
or subfabric but does not define the financial boundary.

Current Railiance scenario names:

| Scenario | Environment | Meaning |
|----------|-------------|---------|
| `bernd-laptop` | `dev` | Private local workstation scenario. It may discover useful loopback services and ports, but it is not a shared developer environment. |
| `coulombcore` | `test` | Central shared test-stage server for developers and friendly early-access users. |
| `railiance01` | `prod` | Production host. It is still alpha-accessible to developers, but the intended direction is restricted production access. |

### Routing Authority

A routing authority is the deployment component that maps an external name,
local URL, ingress host, or port to a backend service. Fabric discovers routing
authority output; it does not allocate ports or author routes.

Examples:

- local loopback process launch configuration for developer tools;
- Makefile or script defaults for local-only bootstrap surfaces;
- Docker Compose published ports;
- Kubernetes `Service`, `Ingress`, or controller-specific route manifests;
- Traefik, nginx, Caddy, HAProxy, or other reverse-proxy configuration;
- DNS records and TLS/certificate automation when they prove reachable names.

### Access Zone

An access zone is a visualization and discovery overlay that describes who a
surface is intended to be reachable by in a deployment scenario. It is not a
fabric boundary and does not define the policy itself.

Useful initial access zones:

| Access zone | Intended reach |
|-------------|----------------|
| `private-dev` | One developer's local machine. |
| `collaborator-test` | Collaborating developers in the shared test stage. |
| `early-access` | Friendly users participating in early access. |
| `production-public` | Production user-facing surfaces. |
| `production-admin` | Production administrative or control surfaces. |

### Policy Authority

A policy authority is the system expected to enforce access rules for a surface.
Fabric may record which authority is in play, such as NetKingdom IAM, an ingress
policy, network policy, or local-only loopback binding, but Fabric does not
define or enforce those rules.

These terms let the graph say: "this service belongs to the Railiance primary
fabric, runs in the `coulombcore` test scenario, is routed by Traefik, and is
intended for the `early-access` zone." That is a deployment and access overlay,
not a change to fabric membership.

## Ownership Rule

Every node in the Fabric graph must carry owner information.

Ownership may be explicit on the node or inherited from the containing fabric or
subfabric, but it must be resolvable. Nodes without resolvable ownership are
incomplete because Fabric cannot explain who is accountable for their cost,
continuity, recovery, or utility.

Ownership should identify the relevant king, lord, tenant, or delegated operator
where applicable. Operators and maintainers may be represented as supporting
actors, but they do not replace the financial boundary terms unless they also
pay for or legally own the responsibility boundary.

## Cross-Boundary Edges

Edges may cross fabric and subfabric boundaries.

These edges are especially important. They are where one owned boundary consumes
utility from another owned boundary. They are also where business value can
appear: paid access, cost recovery, shared platform utility, tenant-facing
interfaces, or contractual service delivery.

Fabric should treat cross-boundary interfaces as first-class graph facts. A
cross-boundary utility edge should be able to identify:

- provider owner;
- consumer owner;
- provider fabric or subfabric;
- consumer fabric or subfabric;
- exposed endpoint, contract, service, or utility;
- durable evidence for the relationship;
- expected payment or business model when known;
- metering basis when known.

The existence of a cross-boundary interface belongs in Fabric. Live usage,
current health, latency, revenue events, and incident state belong to telemetry,
accounting, or operational systems outside the Fabric core.

## Cost And Profit Center Attribution

Cost centers and profit centers are accounting attributions. They are not fabric
boundaries by themselves.

A cost center may be evidence that a responsibility boundary exists, especially
when it corresponds to a lord who pays for infrastructure. However, the fabric
boundary is still established by financial and operational accountability, not
by the accounting label alone.

Cost and profit center attribution may overlap with fabrics and subfabrics:

- one fabric may contain many cost centers;
- one tenant may span several cost centers;
- one cost center may include nodes from multiple subfabrics;
- one shared service may allocate cost across several tenants or cost centers;
- one cross-boundary utility may be cost-bearing for one actor and
  profit-bearing for another.

Fabric should therefore support optional accounting attribution on nodes and
edges without allowing that attribution to redefine containment:

- node cost center;
- node profit center;
- edge cost allocation model;
- edge profit attribution;
- payment schema;
- metering or allocation basis when known;
- attribution validity period when known.

This lets Fabric build cost-center and profit-center views while preserving the
durability of fabric membership. A node moving from one cost center to another
does not necessarily move fabrics. A node moves fabrics only when financial or
operational responsibility for the infrastructure boundary changes.

Useful accounting views include:

- all infrastructure attributed to a cost center;
- all cross-boundary utility edges attributed to a profit center;
- tenant-facing utilities without a payment schema;
- shared services with unresolved allocation;
- owned nodes without cost-center attribution;
- expensive or critical infrastructure with no visible value interface.

## Discovery Approach

Fabric discovery should start from accountability roots, not from arbitrary repo
ownership declarations.

Useful roots include:

- the king and current netkingdom inventory;
- lords and their fabrics;
- tenants and their subfabrics;
- State Hub attached repositories and known host paths;
- Gitea organizations and repository URLs;
- deployment automation repositories;
- Docker, Compose, Kubernetes, systemd, reverse proxy, and infrastructure
  manifests;
- backup, recovery, and secret-management evidence;
- service endpoint and API specifications;
- CI/CD and release automation that proves deployables and deployment targets.

The scanner follows these roots outward to discover durable evidence of nodes
and edges. Repository-local facts can still help identify deployables, APIs, and
artifacts, but repository-owned declarations should not be the default source of
truth for external fabric relations.

## Rebuild From Scratch

A full rebuild should be deterministic enough to repeat and provenance-rich
enough to review.

Recommended phases:

1. Establish the netkingdom root and current king.
2. Register known lords, fabrics, tenants, and subfabrics.
3. Register durable discovery roots for each fabric and subfabric.
4. Crawl deployment automation, infrastructure manifests, repo inventories,
   service configs, and endpoint contracts.
5. Store raw evidence with source paths, URLs, timestamps, scanner versions, and
   content hashes.
6. Normalize identities across host paths, repository URLs, image names, service
   names, endpoint names, and deployment names.
7. Build candidate graph nodes and edges.
8. Resolve or flag ownership for every node.
9. Promote accepted candidates into a versioned fabric snapshot.
10. Export the accepted snapshot to State Hub as a read model.

## Keeping The Model Up To Date

Fabric freshness should be based on durable configuration and automation changes,
with scheduled rescans as a safety net.

Rescan triggers include:

- deployment automation changes;
- infrastructure manifest changes;
- State Hub attached repository inventory changes;
- repository changes that affect deployables, APIs, images, service names,
  endpoint contracts, ports, or deployment configuration;
- tenant or lord changes;
- backup, recovery, or secret-root changes;
- manual operator requests;
- scheduled periodic rebuilds.

Normal source-code edits do not necessarily change the Fabric graph. Fabric
should focus on changes that alter durable topology, ownership, deployment,
interfaces, or cross-boundary utility.

Each update should compare new discovery output with the previous accepted
snapshot and produce a delta. The delta should distinguish:

- added, changed, and removed nodes;
- added, changed, and removed edges;
- changed ownership;
- changed fabric or subfabric membership;
- new or removed cross-boundary utility interfaces;
- ambiguous identity merges that need review;
- discovered nodes without resolvable ownership.

## Boundary With Security Terms

Fabric should avoid using security-zone language for its core concepts.

Terms such as realm, domain, tenant realm, identity realm, and security domain
are useful in systems such as Microsoft environments or Keycloak, but they carry
security and identity-management semantics. Fabric may later relate to those
systems as discovered evidence, but the core Fabric concept is financial and
operational responsibility, not identity or access-control topology.

For now, use:

- king, lord, and tenant for financial responsibility actors;
- fabric and subfabric for durable responsibility boundaries;
- view for diagnostic graph slices;
- environment for deployment classification;
- deployment scenario for a concrete place where services run;
- routing authority for the component that maps names or ports to services;
- access zone for the visualization overlay that groups intended reachability;
- policy authority for the external system expected to enforce access rules.

Access zones may be security-relevant, but they are not Fabric security policy.
They are discovered and visualized evidence that helps operators spot misplaced
surfaces, missing policy authorities, or accidental exposure.

## State Hub Role

State Hub coordinates work and stores a readable projection of the Fabric graph.
It should not be the primary author of Fabric topology.

`railiance-fabric` discovers, normalizes, versions, and exports Fabric snapshots.
State Hub imports those snapshots so agents and operators can ask practical
questions about work, ownership, dependencies, and cross-boundary utility.