generated from coulomb/repo-seed
refactoring for canon conformity
This commit is contained in:
140
docs/canon-alignment-review.md
Normal file
140
docs/canon-alignment-review.md
Normal file
@@ -0,0 +1,140 @@
|
||||
# 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 of truth for repo-owned 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.
|
||||
100
docs/canon-interface-card.yaml
Normal file
100
docs/canon-interface-card.yaml
Normal file
@@ -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.
|
||||
@@ -90,6 +90,11 @@ The JSON export has two top-level arrays:
|
||||
- `edges`: graph relationships such as `provides`, `exposes`,
|
||||
`available_via`, `consumes`, `binds:<status>`, and `uses_interface`
|
||||
|
||||
Canon-aligned exports also carry mapping metadata beside the existing Fabric
|
||||
terms: nodes include `canon_category`, `canon_anchor`, `mapping_fit`, and
|
||||
`evidence_state`; edges include `canonical_type`, `display_only`,
|
||||
`mapping_fit`, and `evidence_state`.
|
||||
|
||||
The graph explorer payload wraps those nodes and edges as Cytoscape-compatible
|
||||
elements with stable keys, layers, display state, visual facets, source
|
||||
references, and deep links. The registry service exposes the same projection at
|
||||
|
||||
@@ -58,6 +58,10 @@ Node fields:
|
||||
| `repo` | Owning repo slug. |
|
||||
| `domain` | Owning domain slug. |
|
||||
| `lifecycle` | Declaration lifecycle. |
|
||||
| `canon_category` | Canon-aligned entity category when known. |
|
||||
| `canon_anchor` | Canon surface that owns the selected category. |
|
||||
| `mapping_fit` | Mapping confidence bucket: `direct`, `partial`, `conflict`, `gap`, or `unknown`. |
|
||||
| `evidence_state` | Evidence state for the node claim: `observed`, `declared`, `inferred`, `proposed`, or `gap`. |
|
||||
|
||||
Edge fields:
|
||||
|
||||
@@ -65,7 +69,10 @@ Edge fields:
|
||||
|-------|---------|
|
||||
| `from` | Source node id. |
|
||||
| `to` | Target node id. |
|
||||
| `type` | Relationship type, such as `provides`, `exposes`, `available_via`, `consumes`, `binds:exact`, or `uses_interface`. |
|
||||
| `type` | Fabric relationship type, such as `provides`, `exposes`, `available_via`, `consumes`, `binds:exact`, or `uses_interface`. |
|
||||
| `canonical_type` | Canon-aligned relationship family when known, such as `exposes`, `depends_on`, `deploys`, or `flows_to`. |
|
||||
| `display_only` | `true` when the edge is a visualization/layout relationship rather than a canonical graph claim. |
|
||||
| `evidence_state` | Evidence state for the claim: `observed`, `declared`, `inferred`, `proposed`, or `gap`. |
|
||||
|
||||
## Proposed State Hub Read Model
|
||||
|
||||
|
||||
Reference in New Issue
Block a user