---
id: graph/construction-json
name: Implement fromJSON and export/toJSON serialization for FlowGraph
status: completed
depends_on:
  - graph/flowgraph-class
  - schema/graph-schemas
scope: narrow
risk: medium
impact: component
level: implementation
---

## Description

Implement the serialization boundary: `FlowGraph.fromJSON()` for deserialization and `export()`/`toJSON()`/`toString()` for serialization. The round-trip `fromSpecs() → export() → fromJSON()` must be lossless.

## Acceptance Criteria

- [ ] `FlowGraph.fromJSON(data: FlowGraphSerialized): FlowGraph` — validates input against schema using `Value.Check()`, throws `InvalidInputError` (with `errors` array) on validation failure
- [ ] `fromJSON()` validates DAG invariants after deserialization — runs cycle detection, throws `CycleError` if cycles found (per ADR-002, even externally-provided data cannot produce cyclic graphs)
- [ ] `export(): FlowGraphSerialized` — returns graphology native JSON format
- [ ] `toJSON(): FlowGraphSerialized` — alias for export()
- [ ] `toString(): string` — `JSON.stringify(export())`
- [ ] Round-trip guarantee: `fromSpecs() → export() → fromJSON()` is lossless
- [ ] Round-trip guarantee: `fromCallEvents() → export() → fromJSON()` is lossless
- [ ] Unit tests: valid round-trips, invalid input throws InvalidInputError, cyclic input throws CycleError, empty graph round-trip

## References

- docs/architecture/flowgraph-api.md — fromJSON, export, toJSON, toString signatures
- docs/architecture/schema.md — SerializedGraph factory, FlowGraphSerialized variants

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion