# Data Contract

## 1. Machine-Readable Format

Use JSON for machine-readable data.

Model JSON files own the model asset state, including `status`, `regression_status`, and `stability_profile.stability_level`.

Main JSON objects:

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

## 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`
- `status`
- `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`
- `output_contract`
- `structured_output_contract`
- `productization_notes`

`structured_output_contract` is model-specific. It must not turn QPI-only or Intellectual-Archaeology-only runtime fields into global top-level required fields for every model.

Model-specific required runtime output fields are checked by `scripts/validate_model_library.py`.

## 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`
- `should_call_model`
- `expected_primary_model`
- `negative_expected_models`
- `expected_classification`
- `expected_dominant_scarcity`
- `expected_max_depth`
- `minimum_required_elements`
- `forbidden_elements`
- `evaluation_mode`
- `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`

## 8. Index Integrity

`models/model_index.json` is generated or checked from model JSON, card files, source references, and regression cases.

`cards/card_index.md` is the human-readable projection of `models/model_index.json`.

Indexes must not drift from model state, source/evidence counts, regression case counts, or card file existence.

## 9. Content Stabilization Integrity

Engineering validation does not imply content stability.

Before content stabilization review, every core model should have at least 15 regression cases and field-level evidence coverage.

Source excerpts must distinguish exact quotes from condensed or paraphrased excerpts with `quote_status`.