archival-agent-spec

Agent Specification: Archival Agent

1. Agent Overview

| Attribute | Value | |-----------|-------| | **Name** | Archival Agent | | **ID** | research-archival-agent | | **Purpose** | Package research artifacts following OAIS standards, manage version control, verify integrity, and maintain backups | | **Lifecycle Stage** | Archival (Stage 5 of Research Framework) | | **Model** | sonnet | | **Version** | 1.0.0 | | **Status** | Draft |

Description

The Archival Agent ensures long-term preservation of research artifacts by creating OAIS-compliant packages (SIP, AIP, DIP), computing and verifying checksums, managing version control integration, and maintaining backup copies. It supports both local and remote storage (S3, Glacier), implements retention policies, and generates reproducibility packages for publication supplements.

2. Capabilities

Primary Capabilities

| Capability | Description | NFR Reference | |------------|-------------|---------------| | SIP Creation | Create Submission Information Packages with content and metadata | NFR-AR-05 | | AIP Generation | Transform SIP to Archival Information Package with preservation metadata | NFR-AR-05 | | DIP Production | Create user-friendly Dissemination Information Packages | NFR-AR-05 | | Checksum Verification | Compute and validate SHA-256 checksums for integrity | NFR-AR-03 | | Remote Backup | Sync archives to S3, Glacier, or institutional repositories | NFR-AR-04 | | Version Management | Track archive versions with incremental/delta packaging | BR-AR-001 |

Secondary Capabilities

| Capability | Description | |------------|-------------| | Archive Manifest | Maintain JSON manifest of all archived packages | | Retention Policies | Enforce retention rules (permanent, time-limited) | | Format Migration | Plan for future format obsolescence | | Integrity Monitoring | Periodic checksum re-verification |

3. Tools

Required Tools

| Tool | Purpose | Permission | |------|---------|------------| | Bash | File operations, compression, checksums | Execute | | Read | Access research artifacts | Read | | Write | Create packages, manifests, logs | Write | | Glob | Discover artifacts for packaging | Read |

System Tools

| Tool | Purpose | Required | |------|---------|----------| | `sha256sum` | Checksum computation | Yes | | `tar` / `gzip` | Archive compression | Yes | | `aws s3` | Remote backup to S3 | Optional | | `git` | Version control integration | Optional |

4. Triggers

Automatic Triggers

| Trigger | Condition | Action | |---------|-----------|--------| | Integration Complete | UC-RF-004 completes | Package artifacts | | Scheduled Archival | Daily/weekly schedule | Incremental archive | | Workflow Completion | UC-RF-008 completes | Final packaging |

Manual Triggers

| Trigger | Command | Description | |---------|---------|-------------| | Immediate Archive | `aiwg research archive --immediate` | Create archive now | | Verify Integrity | `aiwg research archive --verify` | Validate checksums | | Export Reproducibility | `aiwg research provenance export --package` | Publication package | | Remote Sync | `aiwg research archive --sync-remote` | Push to cloud storage |

5. Inputs/Outputs

Inputs

| Input | Format | Source | Validation | |-------|--------|--------|------------| | Research Artifacts | Files | `.aiwg/research/` | Valid files exist | | Archive Schedule | Cron expression | Configuration | Valid cron | | Remote Config | YAML | Configuration | Valid credentials |

Outputs

| Output | Format | Location | Retention | |--------|--------|----------|-----------| | SIP | Directory structure | `.aiwg/archives/SIPs/` | Temporary (delete after AIP) | | AIP | Directory structure | `.aiwg/archives/AIPs/` | Permanent | | DIP | Directory + HTML | `.aiwg/archives/DIPs/` | Permanent (refresh on update) | | Archive Manifest | JSON | `.aiwg/archives/archive-manifest.json` | Permanent | | Validation Logs | Text | `.aiwg/archives/validation-logs/` | 1 year | | Archival History | Text | `.aiwg/archives/archival-history.log` | Permanent |

Output Schema: Archive Manifest JSON

{
  "archive_version": "1.0",
  "created_date": "2026-01-25T02:00:00Z",
  "last_archival": "2026-01-25T02:00:00Z",
  "packages": [
    {
      "package_id": "AIP-2026-01-25-001",
      "package_type": "AIP",
      "creation_date": "2026-01-25T02:00:00Z",
      "item_count": 30,
      "total_size_bytes": 5242880,
      "checksum_algorithm": "SHA-256",
      "verification_status": "PASSED",
      "storage_locations": {
        "primary": ".aiwg/archives/AIPs/AIP-2026-01-25-001/",
        "remote": "s3://research-archives/AIP-2026-01-25-001/"
      },
      "backup_verified": true
    }
  ],
  "retention_policy": {
    "aip_retention": "permanent",
    "sip_retention": "delete-after-aip-verified",
    "validation_log_retention": "1-year"
  }
}

Output Schema: SIP/AIP Directory Structure

AIP-2026-01-25-001/
├── SIP-2026-01-25-001/
│   ├── content/
│   │   ├── sources/         # REF-XXX metadata and summaries
│   │   ├── integrations/    # Citations, bibliography
│   │   ├── quality/         # Quality assessment reports
│   │   └── acquisition/     # Acquisition logs
│   ├── metadata/
│   │   ├── descriptive.xml  # Dublin Core
│   │   ├── preservation.xml # PREMIS
│   │   └── technical.xml    # Format info
│   └── manifest.txt         # SHA-256 checksums
├── archival-metadata/
│   ├── aip-description.xml
│   ├── preservation-history.log
│   └── access-rights.xml
└── checksum-validation.txt

6. Dependencies

Agent Dependencies

| Agent | Relationship | Interaction | |-------|--------------|-------------| | Citation Agent | Upstream | Receives bibliography for packaging | | Provenance Agent | Collaborative | Includes provenance in packages | | Workflow Agent | Orchestrator | Receives task assignments | | All Agents | Observer | Archives artifacts from all agents |

Service Dependencies

| Service