info-tech-canon/infospace/evaluations/railiance-fabric/entity-edge-capture-criteria.yaml

id: conformance/railiance-fabric/entity-edge-capture-criteria
title: Railiance Fabric Entity And Edge Capture Criteria
status: candidate
consumer: railiance-fabric
conformance_pack: conformance/railiance-fabric
entity_categories:
  - id: service
    canon_anchor: model/landscape
    required_fields: [id, kind, title, owner, lifecycle_state, source, provenance]
    expectation: Captures business, application, or technical service without collapsing runtime deployment details.
  - id: software-system
    canon_anchor: model/landscape
    required_fields: [id, kind, title, owner, repository_refs, deployment_refs, source]
    expectation: Captures software system or component boundary.
  - id: runtime-resource
    canon_anchor: model/landscape
    required_fields: [id, kind, title, environment, platform, observed_state, source]
    expectation: Captures workload, cluster, namespace, container, VM, or cloud resource as runtime reality.
  - id: source-repository
    canon_anchor: model/devsecops
    required_fields: [id, kind, title, owner, url_or_path, default_branch, source]
    expectation: Captures source-of-truth repository without treating it as the deployed service.
  - id: pipeline
    canon_anchor: model/devsecops
    required_fields: [id, kind, title, repository_ref, trigger, produced_artifacts, source]
    expectation: Captures delivery workflow that produces artifacts or deployments.
  - id: deployment
    canon_anchor: model/devsecops
    required_fields: [id, kind, title, environment, artifact_ref, runtime_ref, source]
    expectation: Captures deployment record as a change from source artifact into runtime.
  - id: endpoint
    canon_anchor: model/network
    required_fields: [id, kind, title, address_or_dns, protocol, owner, source]
    expectation: Captures network reachability point without hiding service or runtime ownership.
  - id: network-zone
    canon_anchor: model/network
    required_fields: [id, kind, title, boundary, policy_refs, source]
    expectation: Captures segmentation or trust boundary.
  - id: flow
    canon_anchor: model/network
    required_fields: [id, kind, source_ref, target_ref, protocol, direction, evidence_ref]
    expectation: Captures observed or declared communication separately from a generic dependency.
  - id: datastore
    canon_anchor: model/data
    required_fields: [id, kind, title, data_domain, classification, owner, source]
    expectation: Captures storage or data product boundary.
  - id: telemetry-signal
    canon_anchor: model/observability
    required_fields: [id, kind, title, signal_type, observed_entity_ref, source]
    expectation: Captures metric, log, trace, alert, incident, dashboard, or operational evidence.
  - id: policy
    canon_anchor: model/governance
    required_fields: [id, kind, title, scope, owner, source]
    expectation: Captures directive or rule governing an entity, edge, or capture claim.
  - id: control
    canon_anchor: model/security
    required_fields: [id, kind, title, objective, applies_to, evidence_refs]
    expectation: Captures preventive, detective, corrective, or compensating control.
  - id: evidence
    canon_anchor: model/observability
    required_fields: [id, kind, title, evidence_type, supports, date_or_version]
    expectation: Captures support for graph claims and conformance assertions.
  - id: task
    canon_anchor: model/task
    required_fields: [id, kind, title, work_type, state, owner, source]
    expectation: Captures remediation, mapping, review, or refactor work created from graph gaps.
  - id: consumer-purpose
    canon_anchor: model/purpose-demand-extension
    required_fields: [id, kind, title, consumer, use_case, demand_signals]
    expectation: Captures why railiance-fabric needs the canon and where it pressures scope.
canonical_edge_categories:
  - type: part_of
    source_category: runtime-resource
    target_category: software-system
    expectation: Structural containment or composition.
  - type: depends_on
    source_category: service
    target_category: service
    expectation: Logical dependency, not necessarily network flow.
  - type: deploys
    source_category: deployment
    target_category: runtime-resource
    expectation: Delivery event or deployment record places artifact into runtime.
  - type: built_from
    source_category: deployment
    target_category: source-repository
    expectation: Runtime state traces back to source.
  - type: exposes
    source_category: service
    target_category: endpoint
    expectation: Service is reachable through an endpoint.
  - type: flows_to
    source_category: flow
    target_category: endpoint
    expectation: Network flow target remains distinct from dependency.
  - type: reads_or_writes
    source_category: service
    target_category: datastore
    expectation: Data access has direction, purpose, and evidence.
  - type: observed_by
    source_category: runtime-resource
    target_category: telemetry-signal
    expectation: Signal observes a concrete entity.
  - type: governed_by
    source_category: service
    target_category: policy
    expectation: Governance artifact applies to captured object or relation.
  - type: implements
    source_category: control
    target_category: policy
    expectation: Control implements or satisfies policy or objective.
  - type: evidenced_by
    source_category: control
    target_category: evidence
    expectation: Evidence supports a control, claim, review, or edge.
  - type: creates_task
    source_category: evidence
    target_category: task
    expectation: Finding, gap, or review creates work only after triage.
display_only_edge_categories:
  - type: grouped_with
    expectation: Visual cluster membership; must not be used as a canonical relationship.
  - type: near
    expectation: Layout adjacency; never a semantic dependency.
  - type: same_color_group
    expectation: Rendering classification; use Tag when semantic classification is needed.
  - type: collapsed_into
    expectation: View aggregation; canonical nodes and edges must remain recoverable.
  - type: highlight_path
    expectation: Temporary user-selected route in a visualization, not graph truth.
capture_rules:
  - Canonical edge types must be drawn from registered mappings or explicitly flagged as candidate.
  - Display-only edges must use display_only: true and must not appear in conformance claims.
  - Every node and edge must carry source and provenance, even when confidence is low.
  - Unknown concepts should be captured as gaps with candidate mapping, not forced into nearest canon concept.
  - Relationship direction must be explicit and stable.
  - Evidence gaps should create review or mapping work instead of silent graph cleanup.