refactoring for canon conformity

docs/canon-interface-card.yaml

@@ -0,0 +1,100 @@
+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 repo-owned graph declarations and discovery output.
+  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.