feat!: decouple node identity from document location

[JBBianchi]

Many thanks for submitting your Pull Request ❤️!

What this PR does / why we need it:

• compute index-free, name-path node ids (/do/step1) that stay stable when sibling tasks are inserted, removed, or reordered
• prefix non-root entry/exit ports with 'port-' to avoid id collisions
• expose each task's indexed RFC 6901 pointer via taskReference, with getNodeByTaskReference/getNodeAtPointer lookup helpers
• derive edge ids from endpoint node ids only, so label edits (if conditions, switch cases) no longer churn edge identity
• render Mermaid nodes under renderer-local aliases (n0, n1, ...) and escape labels, so any task name yields valid diagram syntax
• allow callers to supply persistent node ids via GraphBuildOptions.taskId on buildGraph/buildFlatGraph/Workflow.toGraph

Copilot summary:
This pull request introduces significant improvements to the workflow graph builder, focusing on stable, pointer-shaped node IDs for tasks, support for custom task ID factories, and enhanced mapping between graph nodes and workflow document pointers. It also updates the MermaidJS diagram output to use renderer-local aliases, ensuring diagram stability regardless of task name changes or special characters. The changes are reflected in both the TypeScript code and documentation.

Graph Node Identity and Customization

• Task node IDs are now stable, pointer-shaped qualified paths based on task names (e.g., /do/step1), making them resilient to sibling task insertions, removals, or reordering. Only renaming or moving a task changes its ID. Non-root entry and exit ports use a port- prefix to avoid collisions, and edge IDs are derived from endpoint node IDs only. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16]
• Added support for a custom taskId factory via GraphBuildOptions, allowing consumers to provide persistent task identities (e.g., for editors that need to keep node identity across renames). The factory receives rich context and must return unique IDs. [1] [2] [3] [4]

Graph-to-Document Mapping

• Each task node now exposes its exact indexed RFC 6901 pointer through a taskReference property, enabling precise correlation between graph nodes and validation/runtime references. Helper functions for node lookup by pointer are documented. [1] [2] [3] [4]

MermaidJS Diagram Output

• MermaidJS diagrams now use renderer-local aliases (n0, n1, ...) instead of graph node IDs, ensuring diagrams remain valid regardless of task name content. The documentation clarifies when to use the graph API for addressable node identities. [1] [2]

Other Updates

• Bumped the package version to 1.0.3-alpha5.
• Simplified edge ID generation to use only source and target node IDs, decoupling edge identity from labels.

These changes collectively make the graph builder more robust, customizable, and easier to integrate with tools that require stable node identities and precise mapping to workflow document structures.

Special notes for reviewers:

Additional information (if needed):

[lornakelly]

Thanks for this PR JB, verified ids locally running against your branch and LGTM

Before (id: "/do/2/uploadToMinio")

After: Before (id: "/do/uploadToMinio")