# 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`.

## 10. Local CCRA Review Run Contract

Local CCRA review runs are process records, not model assets.

They live under:

```text
local_ccra_reviews/<public-round>/<local-pass>/
```

Each local pass should contain:

- `run-notes.md`
- `review-metadata.json`
- `gate-manifest.yaml`
- `lifecycle-guard-config.yaml`
- `agent-invocation-packet.md`
- `prompt-to-send.md`
- `turn-prompts/`
- `review-context.md`
- `review-file-manifest.json`
- `helper-outputs/`
- `04_LOCAL_CCRA_REVIEW_REPORT.md`
- `next-review-requirements.md`
- `returned-output.md`
- `owner-decision.md`

`review-metadata.json`, `review-file-manifest.json`, and helper JSON outputs are machine-readable process records.

Markdown files in the run directory are human-readable process records.

`04_LOCAL_CCRA_REVIEW_REPORT.md` is the `review_turn` judgment output.

`next-review-requirements.md` is the same-child `planning_turn` output and should not be treated as Owner approval or proof that a patch worked.

For Local CCRA v0.1.2 and later, `review-metadata.json` or `agent-invocation-packet.md` must declare:

- `bundle_audit_profile`: `ccra_mindscape_review_bundle`, `generic`, or `not_applicable`.
- `gate_execution_mode`: `dry_run`, `run`, `owner_waived`, or `not_applicable`.
- `routing_diff_policy`: `required`, `skipped_no_after_evidence`, `manual_equivalent_required`, or `not_applicable`.
- `lifecycle_scan_scope`: `current_review_bundle`, `changed_files`, `knowledge_assets`, `model_library_state`, or `whole_repo`.

`returned-output.md` should include the compact Owner-facing summary defined by CCPE v0.1.2, including evidence limitations for the four fields above.

Local CCRA review records must not become source of truth for model status, selector behavior, regression cases, or source evidence. Accepted actions must be applied back to the canonical project files and validated there.

Formal Web CCRA upload bundles exclude the Local CCRA report by default unless the owner explicitly asks to include it.