# Graph Relationship Contracts
#
# Contracts for the `graph` field present in all content metadata schemas.
# Consumed exclusively by the content-graph rustelo feature to build a
# knowledge graph connecting content items with each other and with on+re
# ontology nodes (Axiom, Tension, Practice, Project) and ADRs.
#
# The `graph` field and all its sub-arrays are optional with empty defaults.
# When the content-graph feature is not active, the build system ignores them
# entirely — zero cost for implementations that do not enable the feature.
#
# Relationship semantics
# ----------------------
# implements  → this content demonstrates or realises an ontology node
# related-to  → symmetric peer relationship (content ↔ content or content ↔ node)
# part-of     → hierarchy: this item belongs to a parent project or series
# references  → citation without implying implementation (e.g. post cites an ADR)
# extends     → specialisation: this item builds upon another

{
  RelationshipKind
    | not_exported
    | doc "Valid edge kinds from a content item to another node (content or ontology)."
    = std.contract.from_predicate (fun k =>
        std.array.elem k ["implements", "related-to", "part-of", "references", "extends"]
      ),

  GraphMeta = {
    implements
      | Array String
      | doc "Ontology node IDs (Practice, Project, Axiom, ADR id) this content implements or demonstrates."
      | default = [],

    related_to
      | Array String
      | doc "Content item IDs or ontology node IDs with a symmetric relationship to this item."
      | default = [],

    part_of
      | Array String
      | doc "Parent content item or project IDs. Expresses hierarchy (e.g. a recipe that belongs to a project)."
      | default = [],

    references
      | Array String
      | doc "IDs cited or linked without implying implementation. E.g. an ADR referenced by a blog post."
      | default = [],

    extends
      | Array String
      | doc "IDs of content items this item specialises or builds upon."
      | default = [],
  },
}