# artifact_schema.yaml
schema_name: trading_code_artifact
schema_version: v1.1
description: >
  Defines the structure for derived knowledge artifacts generated from
  trading system source code. Artifacts capture factual structure,
  interpretive intent, invariants, and validated tags for reasoning
  and retrieval by the AI backend.

required_fields:
  - source_file
  - schema_version
  - factual_summary
  - tags

optional_fields:
  - methods
  - interpretive_summary
  - invariants
  - provenance

field_definitions:

  source_file:
    type: string
    description: Relative path to the source file in the trading repository.
    constraints:
      - non_empty
      - relative_path

  schema_version:
    type: string
    description: Version of the artifact schema used to generate this artifact.

  factual_summary:
    type: text
    description: >
      Objective description of what the file or module does.
      Focuses on responsibilities and structure, not rationale.
    constraints:
      - min_length: 40
      - max_length: 500
      - no_interpretive_language

  methods:
    type: object
    optional: true
    description: >
      Optional method-level descriptions for classes or modules where
      fine-grained behavioral understanding is useful.
    method_definition:
      signature:
        type: string
      description:
        type: text
        constraints:
          - no_implementation_details
          - max_length: 200

  interpretive_summary:
    type: text
    optional: true
    description: >
      High-level explanation of why the file exists, what architectural
      role it plays, and what tradeoffs or risks it is designed to manage.
    constraints:
      - min_length: 40
      - max_length: 500
      - no_code_identifiers

  invariants:
    type: list
    optional: true
    description: >
      Conditions that must always hold true for correct behavior.
    item_constraints:
      - type: string
      - min_length: 10

  tags:
    type: object
    description: >
      Classification metadata for the artifact. All tag dimensions
      and values must conform to the backend tag schema.
    constraints:
      - validated_against_tag_schema

  provenance:
    type: object
    optional: true
    fields:
      generated_at:
        type: datetime
      generated_by:
        type: string
      source_commit:
        type: string
      confidence_score:
        type: float
        constraints:
          - min: 0.0
          - max: 1.0