V2 Development Rules

---
description: V2 API development conventions including data model, naming, primary keys, migrations, testing, and documentation. Apply when working on v2 code, v2 API, v2 tests, v2 database, or v2 migrations.
alwaysApply: false
---

# V2 Development Rules

## Reference Files
- Database schema: `v2-schema.dat` (DBML format)
- Development plan: `v2-api-implementation-editable.plan.md` -- if "STOP" appears, halt and wait for user feedback

## Naming Conventions
- Database columns: snake_case
- API fields: camelCase, mapping directly to DB columns (e.g., `orgUid` -> `org_uid`, `metaKey` -> `meta_key`)

## Paths
- CHIA_ROOT: `~/.chia/mainnet/`
- CADT config: `~/.chia/mainnet/cadt/config.yaml`
- V2 database: `~/.chia/mainnet/cadt/v2/`

## Primary Keys (CRITICAL)
- Data tables: VARCHAR(36) storing UUID v4, generated via `uuid.v4()` in application code
- System tables: INTEGER AUTO_INCREMENT
- NEVER use INTEGER PRIMARY KEY AUTOINCREMENT for data tables

## Foreign Keys
- Application-level validation only (no DB constraints)
- Check both main table AND staging table for references

## Timestamps
- Managed by Sequelize (`created_at`, `updated_at`)
- Reject if provided in POST/PUT requests

## API Request Patterns (CRITICAL)
- PUT requests: MUST include ALL fields, not just changed ones
- POST requests: include all required fields
- Same validation schema for CREATE and UPDATE
- **Most list endpoints require `page` and `limit`**: Entity data endpoints (`program`, `methodology`, `issuance`, `label`, `stakeholder`, `stakeholder-projects`, `unit-label`, `project-methodology`, `estimation`, `location`, `rating`, `co-benefit`, `validation`, `verification`, `staging`, `audit`, and all `aef-*` tables) enforce `paginationSchema` — omitting `page`/`limit` returns 400 (`"page is required","limit is required"`). Always include `.query({ page: 1, limit: <N> })`.
- **`project` and `unit`** require `page`/`limit` UNLESS `xls=true` is also passed (XLS export mode skips pagination).
- **Endpoints that do NOT require pagination**: `organizations`, `governance`, `offer`, `filestore`, and `health/*` endpoints return all results without `page`/`limit`.

## Staging and On-Chain Data Validation (CRITICAL)
- Every record staged to `StagingV2` — regardless of entry path (REST API,
  XLSX import, CSV batch import, split/transfer flows, or any future path) —
  must pass the same validation as the REST API: Joi schema, FK existence,
  and NOT NULL completeness. Use `validateStagedRecord` in
  `src/utils/v2-staging-validation.js`; do not hand-roll per-path checks.
- Rationale: staged records become on-chain DataLayer values verbatim, and
  every subscriber re-ingests them into models with `allowNull: false`
  columns. A single incomplete record permanently halts sync for all
  subscribers of the registry.
- `StagingV2.assertChangeListNotNullCompleteness` is a last-line-of-defense
  commit gate (NOT NULL only). It must never be the only validation on a
  write path.
- Any new write path must call the shared validator and add a parity test
  proving the same invalid payload is rejected identically via the API path.

## Migration Patterns (CRITICAL)
- Data table PK: `{ type: Sequelize.STRING(36), primaryKey: true, allowNull: false, unique: true }`
- NO `autoIncrement: true` for data tables

## Error Handling
- Include a clear user-facing message in all application errors

## Testing
- Run v2 tests individually (`npm run test:v2`) to avoid v1 interference
- Write tests alongside new/modified endpoints -- do not defer to a later phase
- After tests pass, stop and ask for user feedback before proceeding
- Prefer simulation mode (`USE_SIMULATOR=true`); datalayer connection errors in simulation indicate a bug

## Documentation
- Update both `/docs/cadt_rpc_api_v2.md` and `/docs/cadt_rpc_api.md` when changing endpoints
- Follow the formatting and structure of existing v1 documentation

## Git
- User handles `git push` -- do not push
- Use `gh` CLI to retrieve GitHub Actions logs