# State Schemas

Atlas's state lives as JSON files under `state/`. Three primary entities + auxiliary collections.

## Primary entity schemas

| File | Spec | Owner |
|------|------|-------|
| `state/projects/PRJ-*.json` | [project.md](./project.md) | `claw-project-tracker` |
| `state/people/<name>.json` | [person.md](./person.md) | `claw-people-observer` |
| `state/customers/CUST-*.json` | [customer.md](./customer.md) | `claw-customer-radar` |

## Auxiliary collections

| File | Purpose |
|------|---------|
| `state/index.json` | Top-level rollup: counts, tier distribution, last update |
| `state/people/aliases.json` | Alias map for identity resolution |
| `state/customers/domain_map.json` | Email-domain → customer ID map |
| `state/extracted/YYYY-MM/<thread_id>/<msg_id>.json` | Canonical Email JSON output of email-extractor |
| `state/runs/YYYY-MM-DD.json` | Daily run snapshot |
| `state/runs/alerts.json` | Andon alert queue (append-only) |
| `state/audit/project_transitions.csv` | Every state transition |
| `state/audit/people_signals.csv` | Every BARS / CCAR signal asserted |
| `state/audit/boss_overrides.csv` | Every boss override applied |
| `state/audit/rule_fires.csv` | Per-rule fire counter |
| `state/unclustered/<thread_id>.json` | Threads claw-project-tracker couldn't cluster |
| `boss_skill.md` | The L1+L2+...+L5 mental model file (see `claw-boss-distiller/`) |
| `boss_skill.history/YYYY-Q*.md` | Quarterly archive of confirmed boss_skill versions |

## Universal conventions

- All timestamps: ISO 8601 UTC with `Z` suffix
- All amounts: number + ISO 4217 currency code
- All `source_email_ids`: arrays, never single string
- All `rule_refs`: machine-readable rule IDs (R-NN, GTD-WF, BARS-proactivity-3, etc.)
- `_meta` block on every entity: `created_at`, `updated_at`, `atlas_version`, plus entity-specific fields

## Privacy & retention

- All state files live INSIDE the client's network. Never copied out.
- Per-customer / per-person right-to-delete commands purge JSON + emit tombstones to `audit/`
- Daily snapshot under `state/runs/` enables point-in-time rollback (last 90 days kept; older compressed to monthly)

## Schema versioning

- Atlas writes its own version into `_meta.atlas_version`
- Schema changes require a migration script under `scripts/migrations/v0.X-to-v0.Y.py`
- Atlas refuses to read state written by a newer schema version (forward-incompatible by design)

## Validation

Each schema doc above will be paired with a JSON Schema (`.schema.json`) when claw skills are implemented in code. Atlas validates every write; invalid writes go to `state/.invalid/` for debugging.