# Schema Snapshots

Per Steven's standing rule (set 2026-05-15): **any JSON data we need
to reference from Foundry V13/V14 or the PF2e/SF2e systems lives here,
as our own snapshot, not as a runtime read of their files.**

## Why

We were reaching into `data/FoundryVTT-WindowsPortable-14.361/Data/
systems/sf2e/sf2e.mjs` and `template.json` at dev time to figure out
what shape SF2e's character data has to be. That works for one machine
but is fragile: every time the SF2e system updates, the surface area
we depend on can shift silently. The Soldier `system.build.languages`
crash that bit us is exactly that: SF2e's prepare pipeline assumed a
field we never knew about, never scaffolded, and never noticed missing
until a Feat tried to read it.

Holding our own snapshot of the surface area we depend on means:

1. **Backwards compat always works.** Old snapshots stay; new variants
   layer on top. We never lose support for an older system version.
2. **One audit trail.** When SF2e or PF2e ships an update, we fetch
   the new schema, diff against our snapshot, and decide what to add
   to a new variant. The diff is the work item.
3. **Air-gapped dev loop.** No need to have a Foundry install present
   to know what fields a character requires; our snapshots answer.
4. **Cog-friendly.** Each snapshot is a small file owned by exactly
   one concern. No monolithic schema dumps.

## Layout

```
src/schema-snapshots/
  README.md                              <-- this file
  sources.json                           <-- provenance log: where each
                                             snapshot came from + version
  sf2e-character-required-fields.json    <-- the build / proficiencies /
                                             perception fields SF2e's
                                             prepare pipeline expects
                                             on a character actor
  ...                                    <-- more snapshots added as
                                             needed (one file per
                                             concern; small files)
```

Snapshots are JSON. Each is a small, focused file describing exactly
the data shape we depend on - never an entire system dump.

## Workflow when a system version changes

1. Fetch the new system's schema source (`data/FoundryVTT-WindowsPortable-
   <ver>/Data/systems/<sys>/template.json`, plus any defineSchema
   blocks the prepare path reads).
2. Diff against the corresponding snapshot file here.
3. If only ADDITIVE changes: layer on top in a new variant file
   (e.g. `sf2e-character-required-fields.v2.json`) and have the
   consuming code prefer the latest variant with fallback to older.
4. If BREAKING changes: bump the snapshot's `schemaVersion`, document
   the break in `sources.json`, and update consumers.
5. Never delete an old snapshot. Backwards compat depends on them.

## Consumers

`src/cogs/<cog>.js` files load snapshots via static JSON imports
(or via `fetch` for the runtime path - to be decided per-snapshot).
The matcher and builder cogs are the primary consumers today; future
cogs (e.g., schema validators) will join.
