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.