flowgraph/tasks/graph-flowgraph-class.md

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

id	name	status	depends_on	scope	risk	impact	level
graph/flowgraph-class	Implement FlowGraph class skeleton wrapping graphology DirectedGraph	completed	schema/enums schema/node-attrs schema/edge-attrs schema/graph-schemas error/hierarchy setup/project-init	moderate	medium	phase	implementation

Description

Create the FlowGraph class that wraps a graphology DirectedGraph and enforces DAG invariants. This is the core data class. At this stage, implement the constructor, generic type parameters, the _graph instance, the graph getter, FlowGraphOptions, and the _edgeKey() helper. Construction factory methods come in dependent tasks.

Acceptance Criteria

• src/graph/construction.ts exports FlowGraph class (or src/graph/index.ts if preferred, matching source structure)
• Class has type parameters: NodeAttrs extends TSchema, EdgeAttrs extends TSchema
• Constructor creates internal graphology.DirectedGraph with options { type: "directed", multi: false, allowSelfLoops: false }
• FlowGraphOptions interface: type?: "directed", multi?: false, allowSelfLoops?: false
• get graph(): DirectedGraph returns the underlying graphology instance
• _edgeKey(source, target): string produces deterministic keys ${source}->${target}
• addNode(key, attrs) — adds node, throws DuplicateNodeError on duplicate
• removeNode(key) — removes node and edges, throws NodeNotFoundError if missing
• updateNode(key, attrs) — partial merge of attributes, throws NodeNotFoundError if missing
• hasNode(key): boolean
• getNodeAttributes(key): NodeAttrs — throws NodeNotFoundError if missing
• addEdge(source, target, attrs?) — throws NodeNotFoundError for missing endpoints, CycleError if edge creates cycle, DuplicateEdgeError if edge exists
• removeEdge(source, target) — no-op if edge doesn't exist
• hasEdge(source, target): boolean
• getEdgeAttributes(source, target): EdgeAttrs — throws if edge doesn't exist
• nodes(): string[], edges(): string[], order: number, size: number
• forEachNode(callback), forEachEdge(callback)
• predecessors(nodeId), successors(nodeId) delegating to graph.inNeighbors/graph.outNeighbors
• Static construction methods (fromSpecs, fromCallEvents, fromJSON) are stubs (throw "not implemented")
• Re-exported from src/graph/index.ts and src/index.ts
• Unit tests: constructor, node operations, edge operations, cycle detection on addEdge

References

• docs/architecture/flowgraph-api.md — FlowGraph class full API surface, delegation model
• docs/architecture/schema.md — edge key convention
• docs/architecture/error-handling.md — throwing contract for mutations

Notes

To be filled by implementation agent

Summary

To be filled on completion