# Contract Schema Notes

Phase 3A introduces Pydantic contracts and JSON Schema exports for the mock-only API Gateway. No TypeScript types are generated yet.

## Pydantic models

Implemented in `apps/api-gateway/jarvis_gateway/contracts.py`:

- `ModuleSnapshot`
- `SourceHealth`
- `KpiItem`
- `AttentionItem`
- `ActionDescriptor`
- `ActivityEvent`
- `ApprovalItem`
- `ReportLink`
- `RedactionPolicy`
- `ModuleRegistryEntry`
- `RuntimeConfig`
- `OverviewResponse`
- `ErrorEnvelope`

The models enforce:

- enum values
- required fields
- `ReportLink.kind` limited to `html`, `pdf`, `markdown`, `json`, `external`
- `ApprovalItem.status` limited to `pending`, `blocked`, `approved`, `rejected`
- RuntimeConfig Option A field names matching ENV prefixes (`jarvis_demo_mode`, `jarvis_public_base_url`, etc.)
- max 3 KPIs per module card
- max 4 modules in overview
- max 5 Attention Items in overview
- no exact Health display in MVP
- no exact Finance display in global overview
- MVP actions limited to `link_only`, `read_only`, `blocked_in_mvp`

## Future TypeScript types

The same contracts should later be mirrored as TypeScript types for the Vue app.

The frontend types should be generated or checked against the same JSON Schema/OpenAPI source to avoid drift.

## JSON Schemas

Phase 3A exports:

- `schemas/module-snapshot.schema.json`
- `schemas/overview-response.schema.json`
- `schemas/module-registry-entry.schema.json`
- `schemas/runtime-config.schema.json`
- `schemas/error-envelope.schema.json`

The schema changelog is in `docs/contracts/schema-changelog.md`.

## Contract tests

Current tests cover:

- examples in `docs/contracts/examples/*.json` validate against Pydantic models
- forbidden fields are absent from examples and API responses
- Finance global values are summary-only
- Health responses contain no raw values, unsafe links or local details
- overview has max 5 Attention Items
- module cards have max 3 KPIs
- disabled actions remain blocked in MVP

## Versioning

Current versions:

- `jarvis.module_snapshot.v1`
- `jarvis.overview.v1`

Breaking contract changes require:

1. version bump
2. ADR or contract changelog
3. updated JSON examples
4. updated backend model tests
5. updated frontend type tests once frontend exists

## Golden fixtures

The files in `docs/contracts/examples/*.json` are golden fixtures.

Adapter-local files in `apps/api-gateway/jarvis_gateway/fixtures/` are temporary copies used by the mock Gateway package. The docs examples remain the source of truth for tests.

All fixtures must stay synthetic.