railiance-fabric/docs/canon-alignment-review.md

# Canon Alignment Review For RAIL-FAB-WP-0016

Date: 2026-05-23

## Review Packet

This review follows the InfoTechCanon consumer alignment workflow for
`railiance-fabric`.

Reviewed Fabric sources:

- `INTENT.md`, `SCOPE.md`, and `README.md`
- `railiance_fabric/graph.py`, `scanner.py`, `registry.py`, and `graph_explorer.py`
- `schemas/discovery-snapshot.schema.yaml` and `schemas/state-hub-export.schema.yaml`
- workplans `RAIL-FAB-WP-0010` through `RAIL-FAB-WP-0016`

Reviewed canon sources:

- `infospace/agent/review-kit/review-kit.yaml`
- `infospace/agent/review-kit/review-workflow.yaml`
- `infospace/evaluations/railiance-fabric/conformance-pack.yaml`
- `infospace/evaluations/railiance-fabric/entity-edge-capture-criteria.yaml`
- `infospace/evaluations/railiance-fabric/mapping-expectations.yaml`
- `infospace/evaluations/railiance-fabric/visualization-examples.yaml`

The workplan's `review-kit/alignment` reference is the canon artifact id; the
physical files are under `infospace/agent/review-kit/`.

## Repository Context

Producer intent: Railiance Fabric owns repo-authored graph declarations,
scanner output, registry projection, validation, query tooling, and State Hub
export contracts for the Railiance ecosystem graph.

Current scope: source-controlled declarations model services, capabilities,
interfaces, dependencies, and binding assertions. Deterministic scanning adds
candidate repositories, libraries, manifests, runtime endpoints, domains,
ports, and source evidence. The graph explorer adds visual projection edges and
inferred runtime views for usability.

Consumer purposes:

- make cross-repo dependencies reviewable,
- make provider/consumer and blast-radius queries reliable,
- provide State Hub with a read model rather than an authoring surface,
- support reingest after a canon-aligned model reset,
- prevent visualization metadata from becoming graph truth.

## Selected Canon Surfaces

| Surface | Why selected |
| --- | --- |
| `model/landscape` | Services, software systems, runtime resources, environments, ownership, and dependency claims. |
| `model/devsecops` | Source repositories, packages, lockfiles, pipelines, artifacts, deployments, and attestations. |
| `model/network` | Endpoints, ports, DNS, routes, reachability, and future flow nodes. |
| `model/data` | Datastore and reads/writes relationships are expected gaps in current Fabric capture. |
| `model/observability` | Evidence, telemetry signals, scanner provenance, and validation support. |
| `model/governance` | Policies, reviews, decisions, exceptions, and reset guardrails. |
| `model/security` | Controls and findings that should not be flattened into generic dependency edges. |
| `model/task` | Review and remediation work created from graph gaps. |
| `model/purpose-demand-extension` | Consumer purpose, scope pressure, and canon evolution feedback. |
| `standard/tagging` | Non-relationship classification without using display edges as semantics. |

## Target Node Taxonomy

| Canon category | Current Fabric source | Fit | Target action |
| --- | --- | --- | --- |
| source-repository | `Repository` candidates and registered repos | direct | Keep as source evidence for repo-local declarations and scans. |
| service | `ServiceDeclaration` | direct | Keep as logical/deployable service boundary. |
| software-system | `CapabilityDeclaration`, `Library`, `ExternalLibrary` | partial | Keep as transitional mapping; later split capability semantics from system/component boundaries. |
| endpoint | `InterfaceDeclaration`, `ApplicationEndpoint`, `NetworkPort`, `DomainName` | partial/direct | Prefer explicit endpoint nodes for network reachability; preserve interface contract attributes. |
| deployment | `DeploymentService`, `ScoreWorkload`, `ContainerBuild` | partial/direct | Add deployment nodes for actual release/deploy evidence before destructive reset. |
| runtime-resource | `RuntimeService`, `Server`, `Kubernetes*` candidates | partial/direct | Capture workload, service DNS, namespace, VM/server, and cluster objects as runtime reality. |
| datastore | none first-class | gap | Add explicit datastore extraction from declarations, manifests, and config before reingest acceptance. |
| flow | route/resolve/port edges only | gap | Add first-class Flow nodes when observed traffic or declared communication needs protocol/evidence context. |
| policy | none first-class | gap | Add policy nodes for governing declarations, reset gates, and validation controls. |
| control | none first-class | gap | Add control nodes only when preventive/detective/corrective controls have evidence. |
| evidence | `BindingAssertion`, `Lockfile`, `ServiceConfig`, contracts, source anchors | partial | Make evidence explicit instead of hiding it only in attributes. |
| task | workplans and review gaps | gap | Capture review/remediation tasks after State Hub readiness work is agreed. |
| consumer-purpose | interface card and purpose-fit review | gap | Keep in docs now; model as graph nodes only if State Hub needs purpose-driven filtering. |
| telemetry-signal | none first-class | gap | Add metrics/logs/alerts/dashboards as observed signals when connectors exist. |

## Target Edge Taxonomy

| Current Fabric edge | Canon relationship | Fit | Notes |
| --- | --- | --- | --- |
| `exposes`, `exposes_port`, `listens_on` | `exposes` | direct/partial | Good first canonical family for service/endpoint reachability. |
| `consumes`, `depends_on_library`, `binds:*`, `uses_interface` | `depends_on` | partial | Preserve helper nodes until a reingest can project direct service relationships safely. |
| `provides` | `implements` | partial | Service-to-capability is a Fabric helper relation; needs stronger canon treatment or collapse. |
| `available_via`, `names_endpoint` | `exposes` | partial | Useful transitional mappings from capability/interface/domain to endpoint. |
| `defines_deployment`, `builds_container`, `declares_package` | `built_from` | partial | Direction and artifact semantics need cleanup before being canonical claims. |
| `defines_runtime_object`, `defines_workload`, `runs_on`, `deployed_as` | `deploys` | partial | Current scanner/UI edges mix source definitions and deployment reality. |
| `routes_to_port`, `routes_to_service`, `resolves_to` | `flows_to` | partial | These are reachability hints, not logical dependencies. |
| `uses_lockfile`, `uses_config`, `documents_interface`, `cataloged_as` | `evidenced_by` | partial | Evidence should become first-class where it supports a specific claim. |
| `declares`, `owns_deployment`, canon display examples | display-only | direct | These are view/cluster edges and must not be conformance claims. |

## Mapping Findings

Direct mappings are strong for repositories, services, runtime resources,
application endpoints, network ports, and explicit `exposes` relationships.

Partial mappings are expected for capability, interface, dependency, binding,
package, manifest, and route concepts. They should keep legacy names during the
transition but carry `canon_category`, `canonical_type`, `mapping_fit`, and
`evidence_state` metadata.

Conflicts: network flow must not be treated as logical dependency, and
graph-explorer layout edges must not be treated as canonical ownership,
dependency, reachability, policy, or evidence.

Gaps: datastores, flows, policy, control, telemetry signals, tasks, and
consumer-purpose nodes are not first-class scanner outputs yet. These should be
implemented as explicit gaps or candidate mappings, not forced into nearby
legacy Fabric semantics.

## Execution Direction

The first implementation slice adds canon metadata beside existing node and
edge names. That keeps registry and graph explorer behavior stable while making
the renewed model inspectable and testable.

The destructive reset phase remains blocked until the following exist:

- export and archive command for current registry graph data,
- reset command that requires an explicit operator flag,
- rollback note that explains restore limits,
- validation that the new scanner/projection can reingest registered repos,
- before/after counts and sample graph review.

No destructive reset was executed during this T01/T02 start.

## Canon Feedback

- Capability and dependency helper nodes are useful Fabric authoring concepts
  but do not map cleanly to canonical graph entity categories.
- Edge direction needs explicit treatment for source repo to package/deployment
  evidence, because canon `built_from` points from deployment/artifact context
  back to source.
- Evidence state should remain independent from review state: accepted inferred
  claims and candidate declared claims are different situations.