# Slice 5: Validation and Error Handling

## Status

Not started

## Objective

Reject invalid project definitions consistently and explain editor, persistence, and Preview failures clearly without losing user work.

## Dependencies

- Canonical schema and backend validator
- Slice 1 component contracts and Slice 2 visual configuration model
- Slice 3 and 4 structured security errors for final integration

## In Scope

- Validation on every persistence path
- Cross-reference and semantic validation
- Editor and Preview diagnostics
- Structured backend errors and safe recovery

## Out of Scope

- AI remediation, arbitrary transforms, and enterprise audit workflows

## Tasks

- [ ] Inventory validation behavior across JSON Apply, create/update, load, and Preview.
- [ ] Centralize backend schema validation and reuse it on every save path.
- [ ] Reject invalid documents without partial persistence updates.
- [ ] Add supported schema-version checks.
- [ ] Validate duplicate IDs/names and dangling action, component, variable, event, and binding references.
- [ ] Validate component-specific properties and binding target compatibility.
- [ ] Standardize backend error codes and response shapes.
- [ ] Surface errors in visual configuration screens and the JSON Editor.
- [ ] Add Preview loading, empty, upstream-error, mapping-error, and recovery states.
- [ ] Preserve unsaved edits when validation or network operations fail.
- [ ] Reconcile examples with canonical binding behavior.
- [ ] Add malformed, semantic, version, and recovery regression tests.
- [ ] Update state and validation documentation.

## Acceptance Criteria

- [ ] No create or update path persists an invalid canonical document.
- [ ] Errors identify actionable paths and messages.
- [ ] Visual Editor, JSON Editor, backend, and Preview agree on supported shapes.
- [ ] Runtime failures are visible without corrupting project or runtime state.
- [ ] Valid examples continue to round-trip.

## Validation

- [ ] Frontend and backend TypeScript checks pass.
- [ ] Validator unit and route tests pass.
- [ ] Valid examples pass and invalid examples fail as expected.
- [ ] Save/load rollback and manual error scenarios pass.

## Risks and Open Questions

- JSON Schema cannot express all semantic rules.
- Severity must distinguish blocking errors from warnings.
- Pre-stable `0.x` documents need a compatibility policy.

## Progress Log

No work recorded yet.

## Handoff

- Last completed: Slice plan created.
- Next action: Build a validation matrix for every entry point and error class.
- Known blockers: Define unsupported schema-version behavior.