# Ontology Response Schema
# Defines response structures for ontology API endpoints:
#   - TypeResponse — entity type listing with hierarchy
#   - SchemaGraphResponse — schema-level relationship graph (L3)
#   - ChainResponse — ontological chain for a type
#   - DistanceResponse — semantic distance between entities
#
# Design principles:
#   - Each sub-structure is COMPOSABLE — usable independently or combined
#   - Consistent with graph-response-schema.kno patterns and vocabulary
#   - Metrics are DERIVED (P10) — computed at query time, never stored
#   - All responses are self-describing: $schema, query context included
#
# Three-Gate Test:
#   Gate 1 (Distinctness): Ontology responses carry type hierarchy and chain
#          semantics that graph-response-schema doesn't model. Graph schema
#          is topology (nodes + edges); this schema is type-system metadata.
#   Gate 2 (Reusability): 4+ endpoints use these structures:
#          GET /ontology/types, GET /ontology/schema-graph,
#          GET /ontology/chain/:type, POST /ontology/distance
#   Gate 3 (Clarity): Separating ontology concerns from graph topology makes
#          both schemas simpler and their roles unambiguous.

$schema: kno@0.0.9

# --- BASIC (kernel) ---
id: 01KJEKRZZNQEEVXJ1BNDHVC9FA
slug: ontology-response-schema
type: spec
version: 0.1.0

# --- STANDARD ---
title: "Ontology Response Schema"
purpose: |
  Response structures for the ontology API layer.

  The ontology API serves *type-system metadata* — what entity types exist,
  how they relate, what chains connect a spec to its instances, and how
  semantically "far apart" two concepts are.

  **Relationship to graph-response-schema:**

  | Concern              | Schema                          |
  |----------------------|---------------------------------|
  | Node/edge topology   | graph-response-schema.kno       |
  | Type hierarchy       | THIS schema (TypeResponse)      |
  | Schema relationships | THIS schema (SchemaGraphResponse) wrapping graph-response-schema nodes |
  | Ontological chains   | THIS schema (ChainResponse)     |
  | Semantic distance    | THIS schema (DistanceResponse)  |

  The SchemaGraphResponse composes graph-response-schema's node/edge types
  for the L3 (schema-level) layer, adding ontology-specific context.

taxonomy:
  topics:
    - ontology
    - api-response
    - type-system
  keywords:
    - schema-graph
    - composable
    - traversal

# --- RICH ---
relationships:
  depends_on:
    - xri: pspace://spec:kno-spec
      reason: "All .kno entities conform to kno-spec"
    - xri: pspace://spec:graph-response-schema
      reason: "SchemaGraphResponse composes GraphNode/GraphEdge for L3 layer"
    - xri: pspace://spec:relationship-vocabulary-schema
      reason: "Predicates in schema-graph edges use canonical vocabulary"
  related_to:
    - xri: pspace://spec:role-schema
      reason: "Ontology access gated by ontology-axis roles (reader → governor)"

# --- DOMAIN: Response Structures ---
#
# Each response type can be used independently. They share a common envelope
# pattern ($schema + endpoint name) for consistency across the API.

response_types:
  # ===========================================================================
  # TypeResponse — GET /api/ontology/types
  # ===========================================================================
  #
  # Returns all known entity types with their hierarchy. The hierarchy is the
  # extends-chain: playbook → document → entity (root).

  TypeResponse:
    description: |
      A listing of all entity types registered in the Possibility ontology.
      Types are returned with their hierarchy depth, parent type (via extends),
      and instance count. The hierarchy is DERIVED from schema `extends`
      relationships — it is not stored separately.
    envelope:
      $schema:
        type: string
        required: true
        description: "Schema reference, e.g., 'ontology-response@0.1.0'"
      endpoint:
        type: string
        required: true
        description: "API endpoint that produced this response"
        example: "/api/ontology/types"
    fields:
      types:
        type: array
        required: true
        description: "All registered entity types"
        items:
          type_entry:
            slug:
              type: string
              required: true
              description: "Entity type slug (e.g., 'playbook', 'user', 'spec')"
            schema_xri:
              type: string
              required: true
              description: "XRI of the governing schema spec"
              example: "pspace://spec:playbook-schema"
            title:
              type: string
              required: true
              description: "Human-readable type name"
            extends:
              type: string
              required: false
              description: "Parent type slug (null for root types)"
              example: "document"
            depth:
              type: integer
              required: true
              description: "Hierarchy depth (0 = root, 1 = direct child, etc.)"
            instance_count:
              type: integer
              required: true
              description: "Number of known instances of this type (derived)"
            status:
              type: string
              required: true
              description: "Schema status"
              enum: [experimental, stable, deprecated]
      total_types:
        type: integer
        required: true
        description: "Total count of registered types"
      max_depth:
        type: integer
        required: true
        description: "Maximum hierarchy depth across all types"

  # ===========================================================================
  # SchemaGraphResponse — GET /api/ontology/schema-graph
  # ===========================================================================
  #
  # Returns the schema-level relationship graph (Layer 3). This composes
  # graph-response-schema's GraphNode and GraphEdge types, adding
  # ontology-specific query context.

  SchemaGraphResponse:
    description: |
      The schema-level relationship graph showing how entity types relate to
      each other via predicates (extends, depends_on, enables, etc.).

      This is a Layer 3 graph: nodes are schemas/types (not instances), and
      edges are structural relationships defined in schema specs.

      The response envelope matches graph-response-schema.kno, with the
      layer fixed to L3 and additional ontology-specific metadata.
    envelope:
      $schema:
        type: string
        required: true
      layer:
        type: string
        required: true
        fixed_value: "L3"
        description: "Always L3 for schema-level graphs"
      endpoint:
        type: string
        required: true
        example: "/api/ontology/schema-graph"
    fields:
      nodes:
        type: array
        required: true
        description: "Schema nodes (GraphNode from graph-response-schema)"
        note: "Each node represents an entity type/schema, not an instance"
      edges:
        type: array
        required: true
        description: "Schema edges (GraphEdge from graph-response-schema)"
        note: "Predicates from relationship-vocabulary-schema; tier is always kernel or container"
      metrics:
        type: object
        required: false
        description: "GraphMetrics from graph-response-schema (derived)"
      type_clusters:
        type: array
        required: false
        description: "Groups of closely-related types (derived from graph structure)"
        items:
          cluster:
            label:
              type: string
              description: "Cluster label (e.g., 'content-types', 'identity-types')"
            types:
              type: array
              description: "Type slugs in this cluster"
      root_types:
        type: array
        required: true
        description: "Types at hierarchy depth 0 (no parent)"

  # ===========================================================================
  # ChainResponse — GET /api/ontology/chain/:type
  # ===========================================================================
  #
  # Returns the ontological chain for a given type — the path from
  # a concrete instance all the way up through schemas, specs, and
  # the root kno-spec. This is the single most important traceability
  # tool in the ontology layer.

  ChainResponse:
    description: |
      The ontological chain for a given entity type. A chain traces the
      full lineage from concrete content through its governing schemas
      up to the root format specification (kno-spec).

      Example chain for a playbook instance:

        my-playbook.kno (instance)
          → playbook-schema.kno (governs)
            → document type (extends)
              → entity type (root)
                → kno-spec.kno (format)

      Chains validate P5 (every entity is schema-governed) and provide
      the foundation for schema evolution impact analysis.
    envelope:
      $schema:
        type: string
        required: true
      endpoint:
        type: string
        required: true
        example: "/api/ontology/chain/playbook"
    fields:
      target_type:
        type: string
        required: true
        description: "The type whose chain was requested"
        example: "playbook"
      chain:
        type: array
        required: true
        description: "Ordered chain links from instance-level to root"
        items:
          chain_link:
            level:
              type: integer
              required: true
              description: "Position in chain (0 = instance level, ascending)"
            slug:
              type: string
              required: true
              description: "Entity/schema slug at this level"
            type:
              type: string
              required: true
              description: "What kind of link (instance, schema, type, spec)"
              enum: [instance, schema, type, format]
            xri:
              type: string
              required: true
              description: "XRI reference for this chain link"
              example: "pspace://spec:playbook-schema"
            relationship:
              type: string
              required: false
              description: "Predicate linking this level to the next (conforms_to, extends, etc.)"
            title:
              type: string
              required: false
              description: "Human-readable title of the entity at this level"
      chain_length:
        type: integer
        required: true
        description: "Total number of links in the chain"
      is_complete:
        type: boolean
        required: true
        description: "Whether the chain reaches kno-spec (root). Incomplete chains indicate orphaned schemas."

  # ===========================================================================
  # DistanceResponse — POST /api/ontology/distance
  # ===========================================================================
  #
  # Returns semantic distance between two entities. Distance is computed
  # via multiple strategies (relationship hops, schema chain comparison,
  # type hierarchy depth difference). Requires authentication (querier+).

  DistanceResponse:
    description: |
      Semantic distance between two entities, computed across multiple
      dimensions. Distance is always DERIVED (P10) — computed at query
      time from the live graph, never cached or stored.

      Three distance types:
        - relationship: BFS shortest path over entity graph edges
        - schema: Steps in the schema extends tree between types
        - chain: Difference in ontological chain depths

      Each distance type returns a numeric score and the path taken.
      Requires authentication with at least querier-level ontology role.
    envelope:
      $schema:
        type: string
        required: true
      endpoint:
        type: string
        required: true
        example: "/api/ontology/distance"
    fields:
      from:
        type: string
        required: true
        description: "Source entity XRI"
        example: "pspace://playbook:my-playbook"
      to:
        type: string
        required: true
        description: "Target entity XRI"
        example: "pspace://user:john-doe"
      distances:
        type: object
        required: true
        description: "Distance measurements by type"
        properties:
          relationship:
            type: object
            required: false
            description: "BFS distance over entity graph edges"
            properties:
              hops:
                type: integer
                description: "Number of edge traversals (null if unreachable)"
              path:
                type: array
                description: "Ordered XRIs of entities along the shortest path"
              predicates:
                type: array
                description: "Predicates traversed along the path"
          schema:
            type: object
            required: false
            description: "Distance in the schema extends tree"
            properties:
              steps:
                type: integer
                description: "Steps between types in extends hierarchy"
              common_ancestor:
                type: string
                description: "Nearest common ancestor type slug"
              path:
                type: array
                description: "Type slugs along the path"
          chain:
            type: object
            required: false
            description: "Ontological chain depth comparison"
            properties:
              depth_difference:
                type: integer
                description: "Absolute difference in chain depths"
              from_depth:
                type: integer
                description: "Chain depth of source entity's type"
              to_depth:
                type: integer
                description: "Chain depth of target entity's type"
      requested_types:
        type: array
        required: true
        description: "Which distance types were requested"
        example: ["relationship", "schema"]
      computed_at:
        type: string
        required: true
        description: "ISO 8601 timestamp when distances were computed (derived, not stored)"

# --- DOMAIN: Composability ---
#
# Response types can be combined. For example, a "type detail" endpoint
# might return a TypeEntry (from TypeResponse) together with its
# ChainResponse and a subset SchemaGraphResponse showing neighbors.

composability:
  description: |
    Each response type is designed for independent use, but they compose
    naturally for richer views:

    | Composition                          | Use Case                                    |
    |--------------------------------------|---------------------------------------------|
    | TypeResponse + ChainResponse         | Type detail page with full lineage          |
    | SchemaGraphResponse + TypeResponse   | Interactive schema explorer with type cards  |
    | DistanceResponse + SchemaGraphResponse| Path visualization between entities         |
    | ChainResponse × N                    | Compare chains across entity types          |

  shared_vocabulary:
    - "XRI references are consistent across all response types"
    - "Type slugs match between TypeResponse.types[].slug and ChainResponse.chain[].slug"
    - "Predicates reference relationship-vocabulary-schema.kno canonical names"
    - "GraphNode/GraphEdge types from graph-response-schema.kno reused in SchemaGraphResponse"

# --- DOMAIN: Examples ---

examples:
  - name: "TypeResponse — small ontology"
    description: "Response from GET /api/ontology/types with three registered types"
    value:
      $schema: "ontology-response@0.1.0"
      endpoint: "/api/ontology/types"
      types:
        - slug: "entity"
          schema_xri: "pspace://spec:kno-spec"
          title: "Entity"
          extends: null
          depth: 0
          instance_count: 0
          status: "stable"
        - slug: "document"
          schema_xri: "pspace://spec:document-schema"
          title: "Document"
          extends: "entity"
          depth: 1
          instance_count: 12
          status: "stable"
        - slug: "playbook"
          schema_xri: "pspace://spec:playbook-schema"
          title: "Playbook"
          extends: "document"
          depth: 2
          instance_count: 5
          status: "experimental"
      total_types: 3
      max_depth: 2

  - name: "ChainResponse — playbook chain"
    description: "Ontological chain from playbook instance to kno-spec root"
    value:
      $schema: "ontology-response@0.1.0"
      endpoint: "/api/ontology/chain/playbook"
      target_type: "playbook"
      chain:
        - level: 0
          slug: "playbook"
          type: "schema"
          xri: "pspace://spec:playbook-schema"
          relationship: "conforms_to"
          title: "Playbook Schema"
        - level: 1
          slug: "document"
          type: "type"
          xri: "pspace://spec:document-schema"
          relationship: "extends"
          title: "Document"
        - level: 2
          slug: "entity"
          type: "type"
          xri: "pspace://spec:kno-spec"
          relationship: "extends"
          title: "Entity (root)"
        - level: 3
          slug: "kno-spec"
          type: "format"
          xri: "pspace://spec:kno-spec"
          relationship: null
          title: ".kno Format Specification"
      chain_length: 4
      is_complete: true

  - name: "DistanceResponse — playbook to user"
    description: "Semantic distance between a playbook and a user entity"
    value:
      $schema: "ontology-response@0.1.0"
      endpoint: "/api/ontology/distance"
      from: "pspace://playbook:my-playbook"
      to: "pspace://user:john-doe"
      distances:
        relationship:
          hops: 2
          path:
            - "pspace://playbook:my-playbook"
            - "pspace://possibility:project-alpha"
            - "pspace://user:john-doe"
          predicates:
            - "part_of"
            - "has_member"
        schema:
          steps: 3
          common_ancestor: "entity"
          path:
            - "playbook"
            - "document"
            - "entity"
            - "user"
        chain:
          depth_difference: 1
          from_depth: 2
          to_depth: 1
      requested_types:
        - "relationship"
        - "schema"
        - "chain"
      computed_at: "2026-02-27T12:00:00Z"

# --- HISTORY ---
_history:
  - version: 0.1.0
    date: "2026-02-27"
    author: pspace-agent
    changes:
      - "Initial creation with four composable response types"
      - "TypeResponse, SchemaGraphResponse, ChainResponse, DistanceResponse"
      - "Consistent envelope pattern ($schema + endpoint)"
      - "Three examples: type listing, chain, distance"