# Data Contract

## 1. Machine-Readable Format

Use JSON for machine-readable data.

Main JSON objects:

- Model spec
- Source article
- Source excerpt
- Regression case
- Selector example

## 2. Human-Readable Format

Use Markdown for:

- Model cards
- Project documentation
- Extraction notes
- Validation reports
- Handoff reports

## 3. Model Spec Contract

Every model JSON should include:

- `model_id`
- `model_name`
- `model_type`
- `pipeline_position`
- `one_sentence_definition`
- `core_question`
- `core_mechanism`
- `source_articles`
- `source_evidence`
- `input_types`
- `output_types`
- `call_when`
- `do_not_call_when`
- `common_misuses`
- `failure_modes`
- `selection_priority`
- `confidence_level`
- `stability_profile`
- `regression_status`
- `productization_notes`

## 4. Source Article Contract

Every source article should include:

- `source_id`
- `title`
- `source_type`
- `related_models`
- `source_status`

Optional:

- `author`
- `date`
- `file_path`
- `notes`

## 5. Source Excerpt Contract

Every source excerpt should include:

- `excerpt_id`
- `source_id`
- `related_model_id`
- `excerpt_type`
- `summary`
- `used_for`

Optional:

- `raw_excerpt`
- `confidence`
- `notes`

## 6. Regression Case Contract

Every regression case should include:

- `case_id`
- `model_id`
- `case_type`
- `input`
- `expected_behavior`
- `failure_signal`

Optional:

- `expected_output_elements`
- `notes`

## 7. Reference Integrity

The following references must be valid:

- `model.source_articles` -> `sources/source_articles.json`
- `model.source_evidence` -> `sources/source_excerpts.json`
- `regression_case.model_id` -> `models/*.model.json`
- `source_excerpt.source_id` -> `sources/source_articles.json`
- `source_excerpt.related_model_id` -> `models/*.model.json`