workflow-shim-forwarding-design

What problem does it solve?

It solves the complexity of maintaining backward-compatible forwarding from the legacy LLMStateGraph* API to the newer WorkflowNet execution model without breaking tracing, status, or stage/output semantics.

Core Features & Use Cases

• Design pattern for forwarding shims: Defines how to map runtime IDs and workflow IDs using a mapping registry to avoid direct dependency on Workflow private symbols.
• Correct Create semantics (two-step capture): Splits workflow structure capture from workflow network registration so the shim can reliably intercept and retain the WorkflowNet.
• Compatibility-preserving state and stage handling: Stores results in both native workflow/global-state form and stategraph-compatible Stages[nodeId][Output] form to keep existing integrations working.
• Trace event conversion: Translates Workflow trace events into XSM/stategraph-style trace events with a deterministic event-type mapping matrix, including a synthetic GraphCreated event when needed.
• Status interoperability with extra keys: Extends status output to include WorkflowId and WorkflowStatus while preserving the legacy 11-key compatibility surface.
• CurrentNode reconstruction: Reconstructs the legacy single CurrentNode by using a sentinel token’s payload path to infer the last executed node.
• Testing guidance for async vs sync completion: Recommends using RunStateGraph with Async disabled when tests require completion guarantees, avoiding Pending status timeouts under registry congestion.

Quick Start

Ask a developer to implement or extend ClaudeOrchestratorWorkflow shim forwarding APIs by following this skill’s mapping registry, two-step Create, dual state/stages storage, trace conversion, and completion-safe testing guidance.