|
| 1 | +# WorkGraph Architecture Roadmap |
| 2 | + |
| 3 | +Date: 2026-03-11 |
| 4 | +Status: Active execution roadmap |
| 5 | + |
| 6 | +## Purpose |
| 7 | + |
| 8 | +This roadmap translates the current WorkGraph vision into the next architectural |
| 9 | +execution phases. |
| 10 | + |
| 11 | +The intent is not to expand the surface area randomly. The intent is to turn |
| 12 | +WorkGraph from a strong local coordination kernel into a real cross-runtime, |
| 13 | +policy-governed, operator-visible company coordination fabric. |
| 14 | + |
| 15 | +## What Is Already True |
| 16 | + |
| 17 | +- The package-first monorepo shape is correct. |
| 18 | +- `packages/kernel` is the right home for truth, lifecycle, policy, triggers, and autonomy semantics. |
| 19 | +- `packages/runtime-adapter-core` is the right home for shared adapter contracts and generic transports. |
| 20 | +- `packages/mcp-server` and `packages/control-api` are the right external surfaces. |
| 21 | +- Local-first markdown + ledger remains a strategic advantage and should stay canonical. |
| 22 | + |
| 23 | +## Core Architectural Delta |
| 24 | + |
| 25 | +The next roadmap is not a package explosion. It is a control-plane hardening and |
| 26 | +runtime-fabric roadmap across five architectural seams: |
| 27 | + |
| 28 | +1. External run broker and runtime correlation |
| 29 | +2. Explicit event transport fabric |
| 30 | +3. Protocol-aware constrained federation |
| 31 | +4. Runtime composition cleanup |
| 32 | +5. First-class projections and operator lenses |
| 33 | + |
| 34 | +## Phase 1: External Run Broker |
| 35 | + |
| 36 | +### Goal |
| 37 | + |
| 38 | +Make WorkGraph runs first-class wrappers around external runtime executions, not |
| 39 | +just local adapter invocations. |
| 40 | + |
| 41 | +### Why |
| 42 | + |
| 43 | +Cross-runtime coordination fails if WorkGraph cannot reliably correlate its own |
| 44 | +`run` primitive with an external runtime job, session, webhook, or execution ID. |
| 45 | + |
| 46 | +### Deliverables |
| 47 | + |
| 48 | +- Extend `run` state to include provider-specific external run identity and |
| 49 | + correlation metadata |
| 50 | +- Normalize external status, log, cancel, follow-up, and evidence reconciliation |
| 51 | +- Add durable inbound reconciliation for runtime webhooks/events |
| 52 | +- Add durable outbound dispatch tracking so retries and recovery are explicit |
| 53 | +- Make Cursor cloud/background execution the first production-grade external path |
| 54 | + |
| 55 | +### Exit |
| 56 | + |
| 57 | +- A run can survive process restarts and still reconcile with the same external |
| 58 | + runtime execution |
| 59 | +- The same WorkGraph thread can dispatch, observe, cancel, and complete work |
| 60 | + across at least one true external runtime without manual operator stitching |
| 61 | + |
| 62 | +## Phase 2: Event Transport Fabric |
| 63 | + |
| 64 | +### Goal |
| 65 | + |
| 66 | +Separate domain truth from delivery mechanics so automation, replay, federation, |
| 67 | + and external runtimes all use the same explicit transport contract. |
| 68 | + |
| 69 | +### Why |
| 70 | + |
| 71 | +The ledger should remain the audit source of truth, but delivery, replay, retry, |
| 72 | +dead-letter handling, and inbound reconciliation need first-class transport |
| 73 | +records rather than implicit side effects of ledger reads. |
| 74 | + |
| 75 | +### Deliverables |
| 76 | + |
| 77 | +- Define outbound event envelope contract and persistence model |
| 78 | +- Add explicit outbox/inbox records for external event delivery and reconciliation |
| 79 | +- Add replay, dead-letter, and operator inspection flows |
| 80 | +- Keep ledger append as the durable audit record while transport records govern |
| 81 | + delivery state |
| 82 | + |
| 83 | +### Exit |
| 84 | + |
| 85 | +- Triggers, webhooks, runtime bridges, and future federation do not depend on |
| 86 | + ad hoc event polling semantics |
| 87 | +- Failed deliveries are inspectable, replayable, and policy-governed |
| 88 | + |
| 89 | +## Phase 3: Protocol-Aware Federation |
| 90 | + |
| 91 | +### Goal |
| 92 | + |
| 93 | +Turn current path-based federation into an explicit same-trust-domain federation |
| 94 | +model that can later grow into network federation without rewriting the kernel. |
| 95 | + |
| 96 | +### Why |
| 97 | + |
| 98 | +The current federation layer is useful but still assumes mounted local paths. |
| 99 | +The vision requires safe cross-workspace references, queries, and eventually |
| 100 | +remote transport-backed collaboration. |
| 101 | + |
| 102 | +### Deliverables |
| 103 | + |
| 104 | +- Formalize remote workspace identity, protocol, and capability metadata |
| 105 | +- Add typed federated links and dereference semantics |
| 106 | +- Add constrained read-only federation as the first supported trust model |
| 107 | +- Add compatibility/version negotiation hooks for future HTTP/MCP remotes |
| 108 | +- Define conflict/authority rules clearly before writable federation exists |
| 109 | + |
| 110 | +### Exit |
| 111 | + |
| 112 | +- Cross-workspace refs and queries are explicit, typed, and inspectable |
| 113 | +- Federation is no longer just “another local path in config” |
| 114 | + |
| 115 | +## Phase 4: Runtime Composition Cleanup |
| 116 | + |
| 117 | +### Goal |
| 118 | + |
| 119 | +Remove remaining runtime-specific composition from kernel bootstrapping so |
| 120 | +WorkGraph stays runtime-agnostic at its core. |
| 121 | + |
| 122 | +### Why |
| 123 | + |
| 124 | +The moat is not “we support Cursor today.” The moat is “any runtime can execute |
| 125 | +against the same trusted coordination substrate.” |
| 126 | + |
| 127 | +### Deliverables |
| 128 | + |
| 129 | +- Move concrete adapter assembly out of kernel-owned registries where possible |
| 130 | +- Make runtime registration/composition flow through package-owned adapter |
| 131 | + surfaces and shared contracts |
| 132 | +- Reduce duplicate runtime lifecycle semantics across kernel and adapter layers |
| 133 | +- Keep kernel focused on orchestration semantics, not runtime instantiation |
| 134 | + |
| 135 | +### Exit |
| 136 | + |
| 137 | +- Kernel defines coordination behavior without hardcoding concrete runtime |
| 138 | + composition as the long-term model |
| 139 | +- Adding a new runtime becomes a package/composition change, not a kernel rewrite |
| 140 | + |
| 141 | +## Phase 5: Projections and Operator Surface |
| 142 | + |
| 143 | +### Goal |
| 144 | + |
| 145 | +Make WorkGraph feel like a company operating surface, not just a capable kernel. |
| 146 | + |
| 147 | +### Why |
| 148 | + |
| 149 | +If the product never becomes watchable, explainable, and operationally legible, |
| 150 | +it risks collapsing into infrastructure admired only by its builders. |
| 151 | + |
| 152 | +### Deliverables |
| 153 | + |
| 154 | +- Promote lenses/projections into explicit read-model contracts |
| 155 | +- Add stronger run, risk, incident, and autonomy attention surfaces |
| 156 | +- Ensure every major control-plane subsystem yields operator-readable state, not |
| 157 | + just internal correctness |
| 158 | +- Tie runtime outcomes back into thread-, mission-, and org-level views |
| 159 | + |
| 160 | +### Exit |
| 161 | + |
| 162 | +- A human operator can open WorkGraph and immediately understand what exists, |
| 163 | + what is active, what is unhealthy, and what needs intervention |
| 164 | +- The system visibly feels like “the company is running on WorkGraph” |
| 165 | + |
| 166 | +## Sequencing Rules |
| 167 | + |
| 168 | +- Do not add many new adapters before one true external runtime path is |
| 169 | + production-grade. |
| 170 | +- Do not attempt writable federation before read-only federation identity and |
| 171 | + authority rules are explicit. |
| 172 | +- Do not add more trigger power without transport, replay, and operator |
| 173 | + visibility improving with it. |
| 174 | +- Do not move kernel logic into control surfaces just to ship faster. |
| 175 | +- Do not let product UX drift away from the actual trusted system state. |
| 176 | + |
| 177 | +## Can Defer |
| 178 | + |
| 179 | +The following are valid roadmap items, but they should not outrank the five core |
| 180 | +architectural seams above: |
| 181 | + |
| 182 | +- many additional runtime adapters beyond the first production-grade external |
| 183 | + path |
| 184 | +- writable cross-workspace federation |
| 185 | +- richer programmable trigger sandboxes beyond today’s composable conditions and |
| 186 | + safety rails |
| 187 | +- fully self-organizing dashboard behavior |
| 188 | +- broad cloud-product packaging work before the local control plane is more |
| 189 | + operationally coherent |
| 190 | + |
| 191 | +## Definition of Success |
| 192 | + |
| 193 | +WorkGraph should be able to truthfully claim all of the following: |
| 194 | + |
| 195 | +- Local-first truth remains canonical |
| 196 | +- External runtimes can execute safely against shared run contracts |
| 197 | +- Automation delivery is replayable and governable |
| 198 | +- Federation is explicit and trusted, not accidental |
| 199 | +- Operator views are first-class projections of the same truth layer |
| 200 | +- The system coordinates humans and multiple runtimes without collapsing into any |
| 201 | + single runtime vendor’s box |
0 commit comments