# Provenance Framework Schema
# Based on REF-062 W3C PROV
# Issues: #243 (PROV-JSON Export), #244 (Provenance Trace)

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/provenance-framework/v1"
title: "Provenance Framework Schema"
description: |
  Provenance tracking and export framework implementing W3C PROV standard
  for PROV-JSON export and derivation tracing per REF-062.

type: object
required:
  - version
  - prov_export
  - provenance_trace

properties:
  version:
    type: string
    pattern: "^\\d+\\.\\d+\\.\\d+$"
    default: "1.0.0"

  prov_export:
    $ref: "#/$defs/PROVExport"

  provenance_trace:
    $ref: "#/$defs/ProvenanceTrace"

$defs:
  PROVExport:
    type: object
    description: "PROV-JSON export per W3C PROV standard"
    properties:
      enabled:
        type: boolean
        default: true

      standard:
        type: string
        default: "https://www.w3.org/TR/prov-json/"

      namespaces:
        type: object
        properties:
          aiwg:
            type: string
            default: "https://aiwg.io/ns/"
          prov:
            type: string
            default: "http://www.w3.org/ns/prov#"

      prov_document_schema:
        type: object
        description: "W3C PROV-JSON document structure"
        properties:
          prefix:
            type: string
            default: "Namespace prefixes"

          entity:
            type: object
            description: "Things with some fixed aspects"
            properties:
              schema:
                type: object
                properties:
                  prov_type: { type: string, default: "Entity type" }
                  aiwg_path: { type: string, default: "File path" }
                  aiwg_hash: { type: string, default: "Content hash (sha256)" }
                  aiwg_created_at: { type: string, default: "Creation timestamp" }

              entity_types:
                type: array
                items: { type: string }
                default:
                  - "aiwg:SourceCode"
                  - "aiwg:Requirement"
                  - "aiwg:Test"
                  - "aiwg:Architecture"
                  - "aiwg:Documentation"
                  - "aiwg:Research"

          activity:
            type: object
            description: "Something that occurs over a period of time"
            properties:
              schema:
                type: object
                properties:
                  prov_type: { type: string, default: "Activity type" }
                  prov_start_time: { type: string, default: "Start timestamp" }
                  prov_end_time: { type: string, default: "End timestamp" }
                  aiwg_agent: { type: string, default: "Agent that performed activity" }

              activity_types:
                type: array
                items: { type: string }
                default:
                  - "aiwg:Implementation"
                  - "aiwg:Testing"
                  - "aiwg:Review"
                  - "aiwg:Documentation"
                  - "aiwg:Refactoring"

          agent:
            type: object
            description: "Something that bears responsibility"
            properties:
              schema:
                type: object
                properties:
                  prov_type: { type: string, default: "Agent type" }
                  aiwg_role: { type: string, default: "Agent role" }
                  aiwg_model: { type: string, default: "LLM model used" }

              agent_types:
                type: array
                items: { type: string }
                default:
                  - "prov:Agent"
                  - "aiwg:AIAgent"
                  - "aiwg:HumanAgent"

          relations:
            type: object
            properties:
              wasGeneratedBy:
                type: object
                properties:
                  description: { type: string, default: "Entity was generated by Activity" }
                  schema:
                    type: object
                    properties:
                      prov_entity: { type: string }
                      prov_activity: { type: string }

              wasDerivedFrom:
                type: object
                properties:
                  description: { type: string, default: "Entity was derived from another Entity" }
                  schema:
                    type: object
                    properties:
                      prov_generated_entity: { type: string }
                      prov_used_entity: { type: string }
                      prov_type: { type: string, default: "Derivation type (aiwg:implements, etc.)" }

              wasAssociatedWith:
                type: object
                properties:
                  description: { type: string, default: "Activity was associated with Agent" }
                  schema:
                    type: object
                    properties:
                      prov_activity: { type: string }
                      prov_agent: { type: string }

              used:
                type: object
                properties:
                  description: { type: string, default: "Activity used Entity" }
                  schema:
                    type: object
                    properties:
                      prov_activity: { type: string }
                      prov_entity: { type: string }

      output_formats:
        type: array
        items: { type: string }
        default:
          - "json"
          - "jsonld"
          - "xml"

      discovery:
        type: object
        properties:
          entity_sources:
            type: array
            items: { type: string }
            default:
              - ".aiwg/**/*.md"
              - "src/**/*.ts"
              - "test/**/*.ts"
              - "docs/**/*.md"

          activity_source:
            type: string
            default: "git log"

          agent_source:
            type: string
            default: ".aiwg/frameworks/registry.json"

          derivation_source:
            type: string
            default: "@-mentions in files"

  ProvenanceTrace:
    type: object
    description: "Derivation query interface per REF-062"
    properties:
      enabled:
        type: boolean
        default: true

      directions:
        type: object
        properties:
          forward:
            type: object
            properties:
              description: { type: string, default: "What depends on this artifact?" }
              query: { type: string, default: "Find all entities derived from source" }

          backward:
            type: object
            properties:
              description: { type: string, default: "Where did this artifact come from?" }
              query: { type: string, default: "Find all entities source was derived from" }

      options:
        type: object
        properties:
          depth:
            type: object
            properties:
              type: { type: string, default: "integer" }
              default: { type: string, default: "unlimited" }
              description: { type: string, default: "Maximum traversal depth" }

          relationship:
            type: object
            properties:
              type: { type: string, default: "array" }
              description: { type: string, default: "Filter by relationship types" }
              examples:
                type: array
                default:
                  - "implements"
                  - "tests"
                  - "extends"
                  - "documents"

          format:
            type: object
            properties:
              type: { type: string, default: "string" }
              enum:
                type: array
                default: ["text", "json", "mermaid", "dot"]
              default: { type: string, default: "text" }

      graph_building:
        type: object
        properties:
          sources:
            type: array
            items: { type: string }
            default:
              - "@-mentions in files"
              - "git history (renames, moves)"
              - "explicit provenance markers"

          caching:
            type: object
            properties:
              enabled: { type: boolean, default: true }
              path: { type: string, default: ".aiwg/provenance/graph-cache.json" }
              invalidate_on_change: { type: boolean, default: true }

      cycle_detection:
        type: boolean
        default: true
        description: "Detect and report circular dependencies"

# Trace result schema
trace_result:
  type: object
  properties:
    root:
      type: string
      description: "Starting artifact path"
    direction:
      type: string
      enum: [forward, backward]
    dependencies:
      type: array
      items:
        type: object
        properties:
          artifact:
            type: string
          relationship:
            type: string
          depth:
            type: integer
          metadata:
            type: object
            properties:
              created_at: { type: string }
              agent: { type: string }
              hash: { type: string }
    cycle_detected:
      type: boolean
    cycle_path:
      type: array
      items: { type: string }

# CLI commands
cli_commands:
  provenance_export:
    command: "aiwg provenance export"
    description: "Export workspace provenance as PROV-JSON"
    options:
      - name: "--output"
        description: "Output file path"
      - name: "--format"
        description: "json, jsonld, xml"
      - name: "--filter"
        description: "Entity type filter (source, test, requirement)"

  provenance_trace:
    command: "aiwg provenance trace <path>"
    description: "Trace derivation chain for artifact"
    options:
      - name: "--forward"
        description: "Find what depends on this"
      - name: "--backward"
        description: "Find what this came from"
      - name: "--depth"
        description: "Maximum depth (default: unlimited)"
      - name: "--relationship"
        description: "Filter by relationship type"
      - name: "--format"
        description: "text, json, mermaid, dot"

  provenance_graph:
    command: "aiwg provenance graph"
    description: "Generate full provenance graph"
    options:
      - name: "--format"
        description: "mermaid, dot, json"
      - name: "--output"
        description: "Output file path"

# Agent protocol
agent_protocol:
  build_prov_document:
    description: "Build PROV-JSON document from workspace"
    steps:
      - initialize_namespaces
      - discover_entities
      - for_each_entity:
          - extract_metadata
          - calculate_hash
          - determine_type
      - extract_activities_from_git
      - for_each_commit:
          - map_to_activity
          - extract_timestamps
      - load_agent_metadata
      - extract_derivations_from_mentions
      - for_each_mention:
          - resolve_target_entity
          - determine_relationship_type
          - create_derivation_record
      - link_entities_to_activities
      - link_activities_to_agents
      - assemble_prov_document
      - validate_against_schema
      - return_prov_document

  trace_derivations:
    description: "Trace derivation chain"
    steps:
      - load_or_build_derivation_graph
      - initialize_visited_set
      - initialize_result
      - traverse:
          - check_depth_limit
          - check_visited
          - mark_visited
          - get_edges_by_direction
          - filter_by_relationship
          - for_each_edge:
              - add_to_result
              - recurse_if_depth_allows
      - check_for_cycles
      - format_by_output_type
      - return_trace_result

  export_graph_format:
    description: "Export graph in visualization format"
    steps:
      - build_derivation_graph
      - select_format_template
      - if_mermaid:
          - generate_mermaid_header
          - generate_node_definitions
          - generate_edge_definitions
      - if_dot:
          - generate_dot_header
          - generate_dot_nodes
          - generate_dot_edges
      - return_formatted_graph

# Storage
storage:
  prov_documents: ".aiwg/provenance/exports/"
  graph_cache: ".aiwg/provenance/graph-cache.json"
  trace_logs: ".aiwg/logs/provenance-trace/"

# Research targets (from REF-062)
research_targets:
  prov_json_export: "W3C PROV-JSON standard export"
  derivation_trace: "Bidirectional derivation queries"
  graph_visualization: "Mermaid/DOT graph output"
  interoperability: "Import into graph databases and analysis tools"

# Example PROV-JSON output
example_prov_json: |
  {
    "prefix": {
      "aiwg": "https://aiwg.io/ns/",
      "prov": "http://www.w3.org/ns/prov#"
    },
    "entity": {
      "aiwg:src/auth/login.ts": {
        "prov:type": "aiwg:SourceCode",
        "aiwg:path": "src/auth/login.ts",
        "aiwg:hash": "sha256:abc123...",
        "aiwg:createdAt": "2026-01-15T10:00:00Z"
      },
      "aiwg:requirements/UC-001.md": {
        "prov:type": "aiwg:Requirement",
        "aiwg:path": ".aiwg/requirements/UC-001-user-authentication.md"
      }
    },
    "activity": {
      "aiwg:activity/impl-login": {
        "prov:type": "aiwg:Implementation",
        "prov:startTime": "2026-01-15T10:00:00Z",
        "prov:endTime": "2026-01-15T11:30:00Z",
        "aiwg:agent": "Test-Engineer"
      }
    },
    "wasGeneratedBy": {
      "_:wgb1": {
        "prov:entity": "aiwg:src/auth/login.ts",
        "prov:activity": "aiwg:activity/impl-login"
      }
    },
    "wasDerivedFrom": {
      "_:wdf1": {
        "prov:generatedEntity": "aiwg:src/auth/login.ts",
        "prov:usedEntity": "aiwg:requirements/UC-001.md",
        "prov:type": "aiwg:implements"
      }
    },
    "agent": {
      "aiwg:agent/test-engineer": {
        "prov:type": ["prov:Agent", "aiwg:AIAgent"],
        "aiwg:role": "Test-Engineer",
        "aiwg:model": "claude-sonnet-4.5"
      }
    },
    "wasAssociatedWith": {
      "_:waw1": {
        "prov:activity": "aiwg:activity/impl-login",
        "prov:agent": "aiwg:agent/test-engineer"
      }
    }
  }

# Example trace output
example_trace_output: |
  $ aiwg provenance trace --forward .aiwg/requirements/UC-001.md

  Tracing forward dependencies from: UC-001-user-authentication.md

  1. src/auth/login.ts
     Relationship: @implements
     Created: 2026-01-15T10:30:00Z
     Agent: Test-Engineer

  2. test/unit/auth/login.test.ts
     Relationship: @tests
     Created: 2026-01-15T09:15:00Z
     Agent: Test-Engineer

  3. docs/api/authentication.md
     Relationship: @documents
     Created: 2026-01-16T14:00:00Z
     Agent: Technical-Writer

  Total: 3 artifacts depend on UC-001

# Example mermaid output
example_mermaid_output: |
  graph TD
    UC001[UC-001: User Authentication]
    LOGIN[src/auth/login.ts]
    TEST[test/unit/auth/login.test.ts]
    DOC[docs/api/authentication.md]

    UC001 -->|implements| LOGIN
    UC001 -->|tests| TEST
    LOGIN -->|documents| DOC

# References
references:
  research:
    - "@.aiwg/research/findings/REF-062-w3c-prov.md"
    - "@.aiwg/research/findings/REF-058-r-lam.md"
  implementation:
    - "#243"
    - "#244"
  related:
    - "@.claude/rules/mention-wiring.md"
    - "@agentic/code/frameworks/sdlc-complete/schemas/flows/fair-extensions.yaml"
    - "https://www.w3.org/TR/prov-json/"