---
id: graph/construction-operation
name: Implement operation graph construction (fromSpecs, addOperation, addTypedEdge)
status: pending
depends_on:
  - graph/flowgraph-class
scope: moderate
risk: medium
impact: phase
level: implementation
---

## Description

Implement the construction methods specific to operation graphs: `FlowGraph.fromSpecs()`, `addOperation()`, and `addTypedEdge()`. These build the static type-compatibility graph from `OperationSpec` arrays.

## Acceptance Criteria

- [ ] `FlowGraph.fromSpecs(specs: OperationSpec[]): OperationGraph` — creates nodes for each operation (key: `${namespace}.${name}`), adds type-compatibility edges via `buildTypeEdges()`, throws `CycleError` if resulting graph has cycles
- [ ] `addOperation(spec: OperationSpec): void` — adds operation node, key is `${spec.namespace}.${spec.name}`, throws `DuplicateNodeError` if key exists
- [ ] `addTypedEdge(source, target, attrs: { compatible, detail?, mismatches? }): void` — adds edge with `edgeType: "typed"`, validates endpoints exist, validates no cycle created
- [ ] `fromSpecs()` calls `buildTypeEdges()` internally after adding all operation nodes
- [ ] `buildTypeEdges()` must be callable separately for incremental construction after `addOperation()`
- [ ] Operation graph is conventionally immutable after `fromSpecs()` — documented in JSDoc
- [ ] Unit tests: fromSpecs with valid specs, duplicate operations, cycle detection, incremental addOperation + buildTypeEdges

## References

- docs/architecture/operation-graph.md — fromSpecs construction, incremental construction, immutability
- docs/architecture/flowgraph-api.md — fromSpecs, addOperation, addTypedEdge signatures

## Notes

> To be filled by implementation agent

## Summary

> To be filled on completion