# Engine schema codegen

Pydantic models in `recoil/api/schemas/engine.py` are the SSOT for engine
entity shapes. The TypeScript types under
`recoil/console-v2/packages/contracts/src/generated.ts` are codegen output.

## How to run

From the repo root:

```bash
python3 -m recoil.api.codegen.pydantic_to_ts
```

Or via pnpm from `recoil/console-v2/`:

```bash
pnpm codegen
```

Both write `recoil/console-v2/packages/contracts/src/generated.ts`.

## CI gate

`recoil/console-v2/packages/contracts/codegen/compare.mjs` re-runs codegen
and `git diff --exit-code`s the output. Drift between the Pydantic source
and the generated TS means someone changed a shape without re-running
codegen — the gate fails loudly per Law 4.

```bash
cd recoil/console-v2 && node packages/contracts/codegen/compare.mjs
```

## Requirements

- Python: `pip install pydantic-to-typescript` (already in
  `recoil/api/requirements.txt`).
- Node: `pnpm add -D -w json-schema-to-typescript` (already in
  `recoil/console-v2/package.json`). `json2ts` is found at
  `recoil/console-v2/node_modules/.bin/json2ts`; the codegen entry point
  resolves it automatically.

## When to re-run

Whenever you edit `recoil/api/schemas/engine.py`. Commit the regenerated
`generated.ts` alongside the Pydantic change.