# Structured Revision History Schema
# Based on REF-061 OAIS (Open Archival Information System)
# Issue: #205

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://aiwg.io/schemas/revision-history/v1"
title: "OAIS-Compliant Structured Revision History Schema"
description: |
  Schema for structured, machine-readable revision history implementing
  OAIS Preservation Description Information (PDI) per REF-061.

type: object
required:
  - version
  - revision_config
  - pdi_mapping

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

  revision_config:
    $ref: "#/$defs/RevisionConfig"

  pdi_mapping:
    $ref: "#/$defs/PDIMapping"

  frontmatter_schema:
    $ref: "#/$defs/FrontmatterSchema"

$defs:
  RevisionConfig:
    type: object
    description: "Revision history configuration"
    properties:
      enabled:
        type: boolean
        default: true

      auto_update:
        type: boolean
        default: true
        description: "Automatically update on file changes"

      storage:
        type: object
        properties:
          location:
            type: string
            enum: [frontmatter, sidecar, embedded]
            default: "frontmatter"
          sidecar_extension:
            type: string
            default: ".revisions.yaml"

      versioning:
        type: object
        properties:
          scheme:
            type: string
            enum: [semver, calver, sequential]
            default: "semver"
          auto_increment:
            type: string
            enum: [patch, minor, none]
            default: "patch"

  PDIMapping:
    type: object
    description: "OAIS PDI category mapping"
    properties:
      provenance:
        type: object
        description: "Processing history and chain of custody"
        properties:
          fields:
            type: array
            items:
              type: string
            default:
              - created_by
              - modified_by
              - processing_history
              - derivation_chain

      context:
        type: object
        description: "Relationships and environment"
        properties:
          fields:
            type: array
            items:
              type: string
            default:
              - related_artifacts
              - dependencies
              - project_phase
              - domain_context

      reference:
        type: object
        description: "Identifiers and versioning"
        properties:
          fields:
            type: array
            items:
              type: string
            default:
              - artifact_id
              - version
              - previous_versions
              - canonical_url

      fixity:
        type: object
        description: "Integrity verification"
        properties:
          fields:
            type: array
            items:
              type: string
            default:
              - checksum
              - checksum_algorithm
              - last_verified

  FrontmatterSchema:
    type: object
    description: "YAML frontmatter schema for revision history"
    properties:
      revision_history:
        type: object
        required:
          - artifact_id
          - current_version
          - revisions
        properties:
          artifact_id:
            type: string
            description: "Unique artifact identifier"
            pattern: "^[A-Z]{2,4}-\\d{3,4}(-[a-z0-9-]+)?$"

          current_version:
            type: string
            description: "Current version string"
            pattern: "^v?\\d+\\.\\d+\\.\\d+$"

          created:
            type: object
            properties:
              date:
                type: string
                format: date-time
              author:
                type: string
              agent:
                type: string
                description: "AI agent if generated"

          revisions:
            type: array
            items:
              $ref: "#/$defs/RevisionEntry"

          provenance:
            type: object
            properties:
              derived_from:
                type: array
                items:
                  type: string
                description: "@-mention references to source artifacts"
              generates:
                type: array
                items:
                  type: string
                description: "@-mention references to derived artifacts"

          fixity:
            type: object
            properties:
              checksum:
                type: string
              algorithm:
                type: string
                enum: [sha256, sha512, md5]
                default: "sha256"
              verified:
                type: string
                format: date-time

  RevisionEntry:
    type: object
    required:
      - version
      - date
      - summary
    properties:
      version:
        type: string
        description: "Version string"
      date:
        type: string
        format: date-time
      author:
        type: string
        description: "Human author (if applicable)"
      agent:
        type: string
        description: "AI agent (if applicable)"
      summary:
        type: string
        description: "Brief description of changes"
      changes:
        type: array
        items:
          type: object
          properties:
            type:
              type: string
              enum: [added, changed, removed, fixed, deprecated]
            description:
              type: string
            section:
              type: string
              description: "Section affected"
      rationale:
        type: string
        description: "Why changes were made"
      review:
        type: object
        properties:
          status:
            type: string
            enum: [draft, reviewed, approved]
          reviewer:
            type: string
          date:
            type: string
            format: date-time
      prov_activity:
        type: string
        description: "Link to PROV activity record"

# Frontmatter template
frontmatter_template: |
  ---
  revision_history:
    artifact_id: "{artifact_id}"
    current_version: "{version}"
    created:
      date: "{created_date}"
      author: "{author}"
      agent: "{agent}"
    revisions:
      - version: "{version}"
        date: "{date}"
        author: "{author}"
        agent: "{agent}"
        summary: "{summary}"
        changes:
          - type: added
            description: "Initial creation"
        rationale: "{rationale}"
        review:
          status: draft
    provenance:
      derived_from:
        - "@{source_artifact}"
      generates: []
    fixity:
      checksum: "{checksum}"
      algorithm: sha256
      verified: "{date}"
  ---

# Example frontmatter
example_frontmatter: |
  ---
  revision_history:
    artifact_id: "SAD-001-architecture"
    current_version: "1.2.0"
    created:
      date: "2026-01-20T10:00:00Z"
      author: "jmagly"
      agent: "architecture-designer"
    revisions:
      - version: "1.2.0"
        date: "2026-01-25T14:30:00Z"
        author: "jmagly"
        agent: "architecture-designer"
        summary: "Added security architecture section"
        changes:
          - type: added
            description: "Security architecture section 5.0"
            section: "5. Security"
          - type: changed
            description: "Updated component diagram"
            section: "3.1 Component Diagram"
        rationale: "Security review identified missing security documentation"
        review:
          status: approved
          reviewer: "security-auditor"
          date: "2026-01-25T15:00:00Z"
        prov_activity: "aiwg:activity/mod-sad-003"
      - version: "1.1.0"
        date: "2026-01-22T09:15:00Z"
        agent: "architecture-designer"
        summary: "Added deployment architecture"
        changes:
          - type: added
            description: "Deployment view section"
            section: "4. Deployment"
        rationale: "Construction phase requires deployment guidance"
        review:
          status: approved
          reviewer: "devops-engineer"
          date: "2026-01-22T11:00:00Z"
      - version: "1.0.0"
        date: "2026-01-20T10:00:00Z"
        author: "jmagly"
        agent: "architecture-designer"
        summary: "Initial architecture document"
        changes:
          - type: added
            description: "Initial creation"
        rationale: "Elaboration phase kickoff"
        review:
          status: approved
          reviewer: "tech-lead"
          date: "2026-01-20T12:00:00Z"
    provenance:
      derived_from:
        - "@.aiwg/requirements/use-cases/UC-001-authentication.md"
        - "@.aiwg/requirements/nfr-modules/security.md"
      generates:
        - "@src/components/auth/"
        - "@.aiwg/testing/integration-test-plan.md"
    fixity:
      checksum: "a1b2c3d4e5f6..."
      algorithm: sha256
      verified: "2026-01-25T15:00:00Z"
  ---

# Sidecar file schema
sidecar_schema:
  type: object
  description: "Standalone revision history sidecar file"
  properties:
    artifact_path:
      type: string
      description: "Path to the artifact this tracks"
    revision_history:
      $ref: "#/$defs/FrontmatterSchema/properties/revision_history"

# CLI commands
cli_commands:
  revision_show:
    command: "aiwg revision show <artifact>"
    description: "Show revision history for artifact"
    options:
      - name: "--format"
        description: "Output format (text, json, yaml)"
      - name: "--limit"
        description: "Number of revisions to show"

  revision_add:
    command: "aiwg revision add <artifact>"
    description: "Add revision entry"
    options:
      - name: "--version"
        description: "Version string (auto-increment if omitted)"
      - name: "--summary"
        description: "Change summary"
      - name: "--author"
        description: "Author name"

  revision_verify:
    command: "aiwg revision verify <artifact>"
    description: "Verify artifact fixity"

  revision_report:
    command: "aiwg revision report"
    description: "Generate revision history report"
    options:
      - name: "--since"
        description: "Show revisions since date"
      - name: "--author"
        description: "Filter by author"
      - name: "--agent"
        description: "Filter by agent"

# Agent protocol
agent_protocol:
  update_revision:
    description: "Update revision history on artifact change"
    triggers:
      - artifact_modified
    steps:
      - load_current_revision_history
      - determine_version_increment
      - create_revision_entry
      - calculate_fixity_checksum
      - update_frontmatter
      - link_to_prov_record
      - persist_changes

  query_revisions:
    description: "Query revision history"
    steps:
      - parse_query_parameters
      - load_revision_history
      - filter_by_criteria
      - format_output
      - return_results

  verify_fixity:
    description: "Verify artifact integrity"
    steps:
      - load_revision_history
      - get_stored_checksum
      - calculate_current_checksum
      - compare_checksums
      - update_verified_timestamp
      - return_verification_result

# Integration with PROV system
prov_integration:
  on_revision_add:
    - create_prov_activity
    - link_revision_to_activity
    - update_derivation_relations

  on_verification:
    - log_verification_activity
    - update_fixity_record

# Storage
storage:
  frontmatter_artifacts: ".aiwg/**/*.md"
  sidecar_path: ".aiwg/revisions/"
  index_path: ".aiwg/revisions/index.json"

# Research targets (from REF-061 OAIS)
research_targets:
  pdi_compliance: "Full OAIS PDI category coverage"
  machine_readable: "Structured YAML vs informal text"
  queryable: "Filter and report on revision metadata"
  integrated: "Links to PROV provenance system"

# References
references:
  research:
    - "@.aiwg/research/findings/REF-061-oais.md"
    - "@.aiwg/research/findings/15-provenance-lineage.md"
  implementation:
    - "#205"
  related:
    - "@agentic/code/frameworks/sdlc-complete/schemas/flows/provenance-system.yaml"
    - "@agentic/code/addons/voice-framework/voices/templates/"
    - "@agentic/code/frameworks/sdlc-complete/templates/"