railiance-fabric/docs/canon-interface-card.yaml

schema: info-tech-canon.interface-card.v1
id: railiance-fabric/interface-card
title: Railiance Fabric Canon Interface Card
consumer:
  repo: railiance-fabric
  domain: railiance
  owner: codex
  intent: Make the Railiance ecosystem understandable, discoverable, and evolvable through accepted Fabric snapshots, accountability-root discovery, and repo-local evidence.
  scope: Shared schemas, validation, graph construction, registry projections, scanner output, and State Hub export contracts for repository, service, capability, interface, dependency, binding, and runtime discovery data.
  purposes:
    - id: purpose/graph-refactor
      use_case: Canon-aligned graph model reset and reingest.
      consumer_need: Separate canonical graph semantics from registry, scanner, and visualization convenience edges before broad adoption.
      demand_signals:
        - RAIL-FAB-WP-0016
        - Registry graph explorer needs clearer canonical/display boundary.
        - Scanner output needs evidence state and canon mapping metadata.
canon_surfaces:
  implemented_profiles: []
  consumed_artifacts:
    - model/landscape
    - model/network
    - model/data
    - model/devsecops
    - model/observability
    - model/governance
    - model/security
    - model/task
    - model/purpose-demand-extension
    - standard/tagging
    - conformance/railiance-fabric
  owned_concepts:
    - FabricGraphExport
    - FabricDiscoverySnapshot
    - GraphExplorerPayload
    - RegistryOnboardingManifest
  produced_concepts:
    - FabricEntity
    - FabricEdge
    - CaptureSource
    - DisplayEdge
    - CanonicalEdgeCandidate
    - VisualizationView
  consumed_concepts:
    - Repository
    - Service
    - SoftwareSystem
    - RuntimeResource
    - Endpoint
    - Deployment
    - Flow
    - Evidence
    - Task
  mappings:
    - source: Repository
      target: source-repository
      fit: direct
    - source: ServiceDeclaration
      target: service
      fit: direct
    - source: InterfaceDeclaration
      target: endpoint
      fit: partial
    - source: CapabilityDeclaration
      target: software-system
      fit: partial
    - source: DependencyDeclaration
      target: depends_on edge
      fit: gap
validation_expectations:
  commands:
    - python3 -m pytest
  evidence_required:
    - Nodes carry canon_category, canon_anchor, mapping_fit, and evidence_state.
    - Edges carry canonical_type, display_only, mapping_fit, and evidence_state.
    - Display-only edges do not act as conformance claims.
    - Reset commands are guarded and documented before graph data is dropped.
  known_gaps:
    - Datastore, flow, policy, control, telemetry-signal, task, and consumer-purpose are not first-class scanner outputs yet.
    - Legacy declaration nodes still preserve capability/dependency/binding helper nodes until reingest rules collapse or replace them safely.
purpose_fit:
  state: partial-fit
  matched_capabilities:
    - entity and edge capture criteria
    - mapping expectations
    - visualization boundary examples
  scope_pressure: Fabric needs a stable edge vocabulary and evidence-state vocabulary for mixed declared, observed, inferred, and proposed graph claims.
  recommended_disposition: Continue consumer-side refactor; record canon gaps as explicit feedback rather than silently extending Fabric semantics.
consumer_needs:
  current:
    - Canon-aligned graph metadata in scanner, registry, export, and graph explorer payloads.
    - Safe destructive reset guardrails before dropping previous graph snapshots.
    - Reingest validation across registered and local repositories.
  requested_extensions:
    - Stable relationship vocabulary for graph capture.
    - Evidence-state vocabulary for captured edges.
    - Visualization boundary guidance for display-only edges.
  feedback:
    - CapabilityDeclaration and DependencyDeclaration are useful Fabric authoring helpers but do not map cleanly to canon node categories.
    - Network flow and logical dependency must remain separate even when both are inferred from the same source artifact.