---
id: error/hierarchy
name: Implement FlowgraphError hierarchy with all error classes and validation result types
status: completed
depends_on:
  - setup/project-init
scope: narrow
risk: low
impact: component
level: implementation
---

## Description

Implement the complete error hierarchy per [error-handling.md](../docs/architecture/error-handling.md). This includes thrown error classes (for construction invariant violations) and structured result types (for validation functions that never throw).

## Acceptance Criteria

- [ ] `src/error/index.ts` exports all error classes and result types
- [ ] `FlowgraphError` base class extending `Error` with `name: "FlowgraphError"`
- [ ] `ConstructionError` extending `FlowgraphError` — base for construction-time errors
- [ ] `DuplicateNodeError` extending `ConstructionError` — `key` property
- [ ] `DuplicateEdgeError` extending `ConstructionError` — `source`, `target` properties
- [ ] `NodeNotFoundError` extending `ConstructionError` — `key` property
- [ ] `CycleError` extending `ConstructionError` — `cycles: string[][]` property
- [ ] `InvalidInputError` extending `ConstructionError` — `errors: ValidationError[]` property
- [ ] `InvalidTransitionError` extending `FlowgraphError` — `requestId`, `from: CallStatus`, `to: CallStatus` properties
- [ ] `ValidationError` interface — `{ type: "schema", nodeKey, field, message, value? }`
- [ ] `GraphValidationError` interface — `{ type: "graph", category: "cycle" | "dangling-reference" | "orphan-node" | "status-inconsistency", details: unknown }`
- [ ] `TypeIncompatError` interface — `{ type: "type-compat", sourceKey, targetKey, compatible: false, mismatches: TypeMismatch[] }`
- [ ] `TypeMismatch` interface — `{ path, expected, actual }`
- [ ] `AnyValidationError` union type — `ValidationError | GraphValidationError | TypeIncompatError`
- [ ] Throwing vs returning contract clearly documented in JSDoc
- [ ] Unit tests: each error class constructs correctly, result types validate, `instanceof` checks work

## References

- docs/architecture/error-handling.md — complete error hierarchy, throwing vs returning contract

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion