flowgraph/tasks/graph-construction-json.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
graph/construction-json	Implement fromJSON and export/toJSON serialization for FlowGraph	completed	graph/flowgraph-class schema/graph-schemas	narrow	medium	component	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