# Schema Contract

This document defines the canonical data and artifact contracts for the prompt
injection evaluation framework. It exists to close the project foundation phase
by making the internal schema explicit and stable.

## Source Of Truth

### Canonical normalized corpus

The canonical normalized attack corpus is:

- `data/normalized/attack_cases.jsonl`

This file is the base machine-readable dataset used by the runner.

### Derived enriched corpus

The taxonomy-enriched derivative is:

- `data/normalized/attack_cases.enriched.jsonl`

This file is generated from the canonical normalized corpus and should be
treated as an analysis-ready derivative, not the primary source of truth.

## Required Attack Case Fields

Each normalized attack case must include:

- `case_id`
- `source_name`
- `source_type`
- `attack_family`
- `attack_surface`
- `prompt`
- `success_criteria`

Recommended optional fields:

- `attack_subtype`
- `context`
- `task_input`
- `expected_target`
- `label`
- `severity_level`
- `benchmark_split`
- `source_reference`
- `source_version`
- `language`
- `created_at`
- `provenance`
- `notes`

## Enriched Attack Case Fields

The enriched mapping layer may add:

- `attack_category`
- `success_definition_id`
- `mapping_confidence`
- `severity`
- `evaluation_mode`
- `mapping_audit`

These fields are additive and must not replace the required normalized fields.

## Experiment Config Contract

The runner expects YAML configs with these sections:

- `experiment`
- `dataset`
- `model`
- `mitigation`
- optional `selection`
- optional `evaluation`

Important active fields include:

- `experiment.name`
- `experiment.seed`
- `experiment.sample_size`
- `experiment.output_dir`
- `dataset.path`
- `model.provider`
- `model.name`
- `model.max_tokens`
- `model.temperature`
- `model.execution_mode`

## Run Artifact Contract

Each run writes a folder under:

- `results/<run_id>/`

With these files:

- `manifest.json`
- `case_results.jsonl`
- `summary.json`

### `manifest.json`

Contains:

- `run_id`
- `timestamp`
- `git_commit`
- `config_source_path`
- `config_snapshot`
- `dataset_snapshot`
- `model_snapshot`
- `mitigation_snapshot`
- `replay_hints`

The `dataset_snapshot` should include enough information to replay selection
deterministically:

- `path`
- `sha256`
- `selected_case_ids`
- `total_available_cases`
- `total_filtered_cases`
- `selection_snapshot`
- `taxonomy_summary`

### `case_results.jsonl`

Contains one record per evaluated case. Current fields include:

- `case_id`
- `source_name`
- `attack_family`
- `attack_surface`
- `attack_category`
- `success_definition_id`
- `mapping_confidence`
- `severity`
- `evaluation_mode`
- `expected_target`
- `request_prompt`
- `request_context`
- `request_task_input`
- `execution_mode`
- `response_text`
- `attack_success`
- `prompt_leakage`
- `refusal`
- `manual_review`
- `matched_rule`
- `latency_ms`
- `provider`
- `model_name`

### `summary.json`

Contains:

- `run_id`
- `experiment_name`
- `aggregate_metrics`
- `result_paths`

## Validation Rule

The loader and runner should reject attack cases that do not satisfy the
required normalized-field contract.