# Derivation Graph Schema
# Based on REF-062 W3C PROV-DM (wasDerivedFrom)
# Issues: #106, #118

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/derivation-graph/v1"
title: "Derivation Graph Schema"
description: |
  Graph structure for tracking artifact derivation chains following W3C PROV-DM.
  Enables queries like "show all tests derived from UC-042".

type: object
required:
  - graph_id
  - nodes
  - edges

properties:
  graph_id:
    type: string
    format: uuid
    description: "Unique graph identifier"

  generated_at:
    type: string
    format: date-time

  scope:
    type: object
    properties:
      root_path:
        type: string
        default: "."
      include_patterns:
        type: array
        items:
          type: string
        default: ["**/*.md", "**/*.ts", "**/*.yaml"]
      exclude_patterns:
        type: array
        items:
          type: string
        default: ["node_modules/**", ".git/**"]
    description: "What files to include in graph"

  nodes:
    type: array
    items:
      $ref: "#/$defs/Node"
    description: "Artifact nodes"

  edges:
    type: array
    items:
      $ref: "#/$defs/Edge"
    description: "Derivation relationships"

  statistics:
    type: object
    properties:
      total_nodes:
        type: integer
      total_edges:
        type: integer
      orphan_nodes:
        type: integer
        description: "Nodes with no incoming edges"
      leaf_nodes:
        type: integer
        description: "Nodes with no outgoing edges"
      max_depth:
        type: integer
      cycles_detected:
        type: boolean
    description: "Graph statistics"

$defs:
  Node:
    type: object
    required:
      - id
      - path
      - type
    properties:
      id:
        type: string
        description: "Unique node identifier"
      path:
        type: string
        description: "File path"
      type:
        type: string
        enum:
          - requirement      # UC-*, US-*, REQ-*
          - use_case         # UC-*
          - user_story       # US-*
          - architecture     # SAD, ADR-*
          - design           # Design documents
          - source_code      # *.ts, *.py, etc.
          - test             # *.test.ts, *.spec.ts
          - research         # REF-*
          - schema           # *.yaml, *.json schemas
          - rule             # .claude/rules/*
          - template         # templates/*
          - other
        description: "Artifact type"
      metadata:
        type: object
        properties:
          title:
            type: string
          created_at:
            type: string
            format: date-time
          hash:
            type: string
          ref_id:
            type: string
            description: "REF-XXX, UC-XXX, etc."
      status:
        type: string
        enum:
          - active
          - deprecated
          - orphaned
          - untracked
        default: active

  Edge:
    type: object
    required:
      - source
      - target
      - relationship
    properties:
      source:
        type: string
        description: "Source node ID"
      target:
        type: string
        description: "Target node ID"
      relationship:
        type: string
        enum:
          # Implementation
          - implements
          - implemented_by
          - tests
          - tested_by
          # Structural
          - extends
          - extended_by
          - depends
          - dependency_of
          # Derivation
          - derives_from
          - source_of
          - references
          - related
          # Semantic
          - contradicts
          - supersedes
          - superseded_by
          - validates
        description: "Relationship type (from qualified-references rule)"
      confidence:
        type: number
        minimum: 0
        maximum: 1
        default: 1
        description: "Confidence in the relationship"
      evidence:
        type: object
        properties:
          mention_line:
            type: integer
          mention_text:
            type: string
          inferred:
            type: boolean
            default: false
        description: "How relationship was detected"

# Query patterns
queries:
  forward_trace:
    description: "Find all artifacts derived from a source"
    example: "Show all tests derived from UC-042"
    traversal: "BFS from source following outgoing edges"

  backward_trace:
    description: "Find all sources an artifact is derived from"
    example: "What requirements does auth.ts implement?"
    traversal: "BFS from target following incoming edges"

  gap_detection:
    description: "Find artifacts missing coverage"
    example: "Find requirements with no test coverage"
    algorithm: "Find requirement nodes with no 'tested_by' outgoing edges"

  orphan_detection:
    description: "Find artifacts with no derivation"
    example: "Find code not linked to any requirement"
    algorithm: "Find code nodes with no 'implements' incoming edges"

  impact_analysis:
    description: "Find all artifacts affected by a change"
    example: "If UC-042 changes, what needs review?"
    traversal: "Full forward trace from changed node"

# Output formats
output_formats:
  text:
    description: "Human-readable text tree"
    example: |
      UC-042: User Authentication
      ├── @implemented-by src/auth/login.ts
      │   └── @tested-by test/auth/login.test.ts
      └── @implemented-by src/auth/session.ts
          └── @tested-by test/auth/session.test.ts

  json:
    description: "Structured JSON for programmatic use"

  mermaid:
    description: "Mermaid diagram syntax"
    example: |
      graph TD
        UC042[UC-042: User Auth]
        SRC1[src/auth/login.ts]
        TEST1[test/auth/login.test.ts]
        UC042 -->|implements| SRC1
        SRC1 -->|tested_by| TEST1

  dot:
    description: "GraphViz DOT format"
    example: |
      digraph G {
        UC042 [label="UC-042: User Auth"];
        SRC1 [label="src/auth/login.ts"];
        UC042 -> SRC1 [label="implements"];
      }

# Agent protocol
agent_protocol:
  build_graph:
    description: "How agents build derivation graph"
    steps:
      - scan_files_for_mentions
      - parse_qualified_references
      - build_node_list
      - build_edge_list
      - detect_cycles
      - compute_statistics

  query_graph:
    description: "How agents query the graph"
    operations:
      - forward_trace
      - backward_trace
      - gap_detection
      - orphan_detection
      - impact_analysis

# Storage
storage:
  location: ".aiwg/provenance/derivation-graph.json"
  cache_ttl: 3600  # Rebuild after 1 hour
  incremental_update: true

# References
references:
  research:
    - "@.aiwg/research/findings/REF-062-w3c-prov.md"
  implementation:
    - "#106"
    - "#118"
  related:
    - "@agentic/code/frameworks/sdlc-complete/schemas/provenance/prov-record.yaml"
    - "@.claude/rules/qualified-references.md"