# Registry Schema — Layer 3 Entity Type
# KNO Schema Version: 0.2.0
# CHANGELOG:
#   0.2.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18.
#
# A Registry entity describes a discovery-surface URL the platform advertises:
# its endpoint, its upstream JSON-Schema URL, and the spec version it pins.
#
# EXTENDS: document-schema.kno (which composes identity, history, quality)
#
# DESIGN DECISIONS:
# - DD-REG-01: Registries are .kno entities; the integration manifest's
#   `registries` block, the bootstrap bundle's `mcp_registry` field, and the
#   A2A agent card's `mcp-registry` skill are all DERIVED from these files.
#   No registry URL is hardcoded in src/.
# - DD-REG-02: Endpoint URL is composed at projection time from a path
#   template (e.g., `/v0.1/servers`) plus `${PSPACE_API_URL}` so a single .kno
#   file is environment-portable across local / staging / production.
# - DD-REG-03: `subtype` discriminates registry kinds. Today: `mcp`. Future:
#   `a2a` (A2A agent registry), `openapi` (OpenAPI catalog), `capabilities`
#   (capability marketplace). One schema, many subtypes — passes the
#   Schema-Minimization Three-Gate Test by serving as the typed pivot
#   between the abstract concept and concrete pointers.
# - DD-REG-04: `spec_version` is the pinned upstream spec version (e.g.,
#   MCP Registry's `2025-12-11`). Pinned, NOT derived from the upstream URL,
#   so the platform can advertise its conformance independently of upstream
#   redirects.
# - DD-REG-05: Compatibility flags (e.g., `github_copilot_compatible: true`)
#   are first-class typed fields, NOT free-form metadata, so consumer agents
#   can reliably gate on them.
#
# THREE-GATE TEST:
#   Gate 1 (Distinctness): YES — a registry pointer is fundamentally different
#     from an `mcp-server` (a registry CONTAINS servers; it is itself a
#     catalog endpoint, not a tool surface). Different from `service-config`
#     (which describes a possibility's binding to provisioned infrastructure).
#     Different from `agent-card` (which describes an agent, not a directory).
#   Gate 2 (Reusability): YES with a planned reusability path. Today there is
#     one instance (mcp). The schema is designed at v0.1.0 to also accept
#     `subtype: a2a`, `subtype: openapi`, etc. without modification — the same
#     fields apply. We cross the 3-instance threshold the moment we expose a
#     second discovery surface (already on the roadmap per DD-REG-03).
#   Gate 3 (Clarity): YES — keeping the registries block typed (instead of
#     burying it in a generic `document` purpose) lets the manifest projector
#     emit a strongly-typed `RegistriesSection` interface and lets the
#     drift-guard test enforce field presence per surface.
#
# USE CASES:
# - MCP Registry (`/v0.1/servers`) — current
# - A2A Agent Registry — planned
# - OpenAPI Catalog — planned
# - Capability Marketplace — planned
#
# MAPS TO: RegistryEntry interface in services/pspace-api/src/lib/registries-collection.ts

# =============================================================================
# SCHEMA DECLARATION
# =============================================================================
$schema: kno@0.0.9

# =============================================================================
# IDENTITY
# =============================================================================
id: 01KQ9V8PAZ7XJW2QHKMG5N3REG
slug: registry-schema
type: spec
version: 0.2.0

# =============================================================================
# VISIBILITY DECLARATION (REQ-18) — collection default
# =============================================================================
# Registry entities (content/registries/*.kno) are public reference knowledge by
# default. Per REQ-18, individual entities MAY override with their own
# `visibility:` field (last-write-wins at the entity level). Drives the
# four-surface contract per kno-system_architecture.md § Agent Surface
# Integration and public-surface-parity.instructions.md.
visibility: public

# =============================================================================
# STANDARD TIER
# =============================================================================
title: "Registry Schema"
purpose: |
  Define the schema for Registry pointer entities — typed descriptors of the
  discovery-surface URLs Possibility advertises across its three discovery
  surfaces (integration manifest, bootstrap bundle, A2A agent card).

  **What is a Registry entity?**
  A Registry entity is a thin pointer record: it names a discovery endpoint
  the platform exposes, the upstream JSON-Schema URL that endpoint conforms
  to, and the spec version pinned. The actual catalog payload (server list,
  agent list, etc.) is served by the endpoint itself — this entity just tells
  consumers where to find it.

  **Why a separate schema (not a document subtype)?**
  Registries have typed fields (`spec_version`, compatibility flags) that
  consumer agents need to gate on reliably. Burying them in a generic
  document with `purpose: registry-pointer` would force every consumer to
  type-cast at runtime. The Schema-Minimization Three-Gate Test passes
  because the schema serves multiple subtypes (mcp, a2a, openapi,
  capabilities) — see DD-REG-03 / Gate 2 above.

  **Surface parity contract:**
  The three discovery surfaces (integration manifest's `registries.{subtype}`
  block, bootstrap bundle's `{subtype}_registry` field, A2A agent card's
  `{subtype}-registry` skill) MUST emit the same `url` and `spec_version` for
  the same registry. A surface-parity test enforces this — the same .kno
  file is the single source of truth (P3, P10).

# =============================================================================
# RICH TIER — Provenance & Taxonomy
# =============================================================================
provenance:
  origin:
    id: 01KQ9V8PAZ7XJW2QHKMG5N3REG
    timestamp: "2026-04-22T00:00:00Z"
    tool: manual

taxonomy:
  topics:
    - registry
    - discovery
    - agent-discovery
    - manifest
  keywords:
    - registry
    - discovery-surface
    - spec-version
    - mcp-registry
    - cross-link

# =============================================================================
# RICH TIER — Relationships
# =============================================================================
relationships:
  extends:
    - xri: "kno://specs/document-schema"
      reason: "Layer 2 base type"

  depends_on:
    - xri: "kno://specs/kno-spec"
      reason: "Conforms to KNO format specification v0.0.9"

  composes:
    - xri: "kno://specs/identity-schema"
      reason: "Layer 1: id, slug, provenance"
    - xri: "kno://specs/history-schema"
      reason: "Layer 1: _history, changelog"
    - xri: "kno://specs/quality-schema"
      reason: "Layer 1: quality, validation"

  related_to:
    - xri: "kno://specs/mcp-server-schema"
      reason: "MCP registry advertises MCP server entities"
    - xri: "kno://specs/agent-card-schema"
      reason: "Future A2A registry will advertise agent-card entities"

# =============================================================================
# RICH TIER — Quality
# =============================================================================
quality:
  status: stable
  last_reviewed: "2026-04-22"
  validation:
    - "Subtype enum is closed: mcp | a2a | openapi | capabilities"
    - "endpoint_path is a path (begins with /), not a full URL"
    - "spec_url is a full URL"
    - "spec_version is a string (date format for upstream specs that use dates)"

# =============================================================================
# CONTENT — Schema Definition
# =============================================================================

# Required fields (per DD-REG-01..05):
#
#   id           ULID — birth identity (immutable)
#   slug         Human-readable identifier (e.g., "mcp-registry")
#   type         "service-config" — Registries are a service-config subtype
#                because they describe a platform-exposed service surface.
#                (Reuses the existing service-config tier without adding a
#                new top-level type — extends, not creates.)
#   subtype      One of: mcp | a2a | openapi | capabilities
#   version      Semver of THIS entity (not the upstream spec)
#   title        Human-readable name
#   description  One-sentence prose summary, ≤120 chars
#   endpoint_path Path the registry is mounted at (e.g., "/v0.1/servers").
#                MUST begin with "/". The projector composes the full URL by
#                prepending ${PSPACE_API_URL}.
#   spec_url     Full URL of the upstream JSON-Schema (or equivalent spec
#                document) the endpoint conforms to.
#   spec_version Pinned upstream spec version. String form so date-keyed
#                specs (like MCP Registry's "2025-12-11") are first-class.
#
# Optional fields:
#
#   compatibility  Map of compatibility flags. Recommended keys:
#                    github_copilot_compatible: bool
#                    cursor_compatible: bool
#                    claude_code_compatible: bool
#                  Compatible consumers can gate on these without parsing
#                  the upstream spec.
#   tags           Array of strings — extra hints for catalogue UIs.
#   _history       Standard history block (created, changes[]).
#   _meta          Standard meta block. Reverse-DNS extensions allowed under
#                  "space.possibility/*".

# =============================================================================
# EXAMPLE
# =============================================================================
# See: content/registries/mcp-registry.kno