Harden registry API and schema validation

docs/registry-api.md

@@ -0,0 +1,67 @@
+# Registry API
+
+The Railiance Fabric registry is a small HTTP API over repo-owned Fabric
+declarations and supporting inventory.
+
+## Health And Status
+
+```text
+GET /health
+GET /status
+```
+
+`/health` is intentionally tiny. `/status` includes database path, table counts,
+and the latest accepted snapshot per repository.
+
+## Repository Snapshots
+
+```text
+POST /repositories
+GET  /repositories
+GET  /repositories/{repo_slug}
+GET  /repositories/{repo_slug}/inventory
+POST /repositories/{repo_slug}/snapshots
+GET  /repositories/{repo_slug}/snapshots
+GET  /repositories/{repo_slug}/snapshots/latest
+GET  /repositories/{repo_slug}/snapshots/diff
+```
+
+Snapshot ingestion accepts a `FabricGraphExport` under `graph` plus `commit`
+and optional `generated_at`.
+
+## Graph Queries
+
+```text
+GET /graph/nodes
+GET /graph/nodes/{graph_id}
+GET /graph/providers?capability_type=runtime-secrets
+GET /graph/consumers?target=railiance-platform.openbao.kv-v2
+GET /graph/unresolved
+GET /graph/blast-radius?interface_id=openbao-kv-v2-mount
+GET /graph/dependency-path?service_id=flex-auth.api
+GET /search?q=jsonschema
+```
+
+## Artifacts And Libraries
+
+```text
+POST /artifacts
+GET  /artifacts
+GET  /artifacts/{artifact_id}
+GET  /libraries
+GET  /libraries/{library_id}
+GET  /repositories/{repo_slug}/libraries
+POST /repositories/{repo_slug}/libraries/cyclonedx
+```
+
+CycloneDX ingestion replaces the repo's current library inventory with the
+components and services in the submitted SBOM.
+
+## Exports
+
+```text
+GET /exports/state-hub
+GET /exports/backstage
+GET /exports/xregistry
+GET /exports/libraries/xregistry
+```