feat(flow): execution mode and the run-level flow token

[rubenvdlinde]

Why

Two engine gaps blocked apps from moving their bespoke chaining onto the flow engine. Both surfaced while migrating OpenConnector (openconnector#1066) — the fifth of the six "flow" systems ADR-065 converts into consumers.

1. A trigger could only ever queue. FlowTriggerService::fire() called FlowRunService::queue() and nothing else. That's the right default, but OpenConnector's object-lifecycle synchronisation runs synchronously inside the triggering save today; migrating it onto a queue-only engine would silently turn a save-time guarantee into an eventually-consistent one. An app couldn't opt out, so the migration either changed behaviour or didn't happen.

2. A node could not write run-level state. The dispatcher contract is dispatch(step, items, context): array — items come back, $context goes in by value and nothing returns. So a value couldn't survive across steps except by riding the item list, which breaks the moment a node fans out or filters (exactly what FlowItems' "context is not the data channel" rule warns about).

What changed

• executionMode on a flow — async (default, today's behaviour) or sync. A sync flow is queued then executed inline, so one persistence path means history/retry/resume treat it identically to a drained run. A sync flow that suspends is left for the worker; the inline call never blocks on a wait.
• FlowToken at context['token'] — a mutable run-level value bag. An object handle survives the by-value array copy, so a node writes to it with zero change to the IFlowNode signature`. The ten registered nodes and both leaf apps (hermiq, openconnector) need no change at all.
• Propagation + return — a sub-flow is seeded with its parent's values (not the parent's instance, so a fire-and-forget child can never mutate a parent that has already moved on); a waited-on child merges its values back, child winning on conflict.
• Pause/continue-later comes free — persistResult() already writes context back on the SUSPENDED path and execute() restores it, so the token is just serialised/rehydrated there. No new column, no migration.

Design notes

• executionMode rides the resolver document, not the flow object, so every store (OR-native, hermiq's, any future IFlowResolver) carries it through one seam. Worth flagging: cron is not precedent here — FlowScheduleService reads it straight off the OR object (scheduleOf(ObjectEntity)), which only works for the OR-native store.
• runInline() is deliberately best-effort: an unresolvable flow or subject leaves the run queued for FlowRunWorker, which already owns the full defensive failure handling. Duplicating those semantics would give the engine two places deciding what a broken run means, and they'd drift.

Backwards compatibility

Absent executionMode ⇒ async. Absent/malformed stored token ⇒ empty token. Existing persisted runs resume normally.

⚠️ The flow schema gains executionMode (version 1.1.0 → 1.2.0). Per openregister#2075 a shipped schema does not gain properties on re-import, so existing installs need the property added to the live schema — the same footnote that applied to cron in #2126.

Verification

• 21 new unit tests (token semantics, by-value write-through, serialise round trip, sub-flow seed/isolation/return/conflict, all five execution-mode branches incl. a throwing sync flow not escaping the trigger)
• 175/175 green across the full tests/Unit/Service/Flow/ suite — the change is signature-neutral
• PHPCS 0 errors on all 6 changed lib/ files
• openspec validate --strict passes (two spec deltas: flow-execution-mode, flow-token)

Live verification on 8080 (task 4.4) is still open.

Unblocks

openconnector-flow-migration Phases 2 and 3, and retires the app-local FlowToken helper OpenConnector carries today.

[github-actions]

Quality Report — ConductionNL/openregister @ 8a9460c

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
composer			✅	✅ 174/174
npm			✅	✅ 555/555
PHPUnit					✅
Newman					✅
Playwright					⏭️

---

Quality workflow — 2026-07-27 09:49 UTC

Download the full PDF report from the workflow artifacts.

[rubenvdlinde]

✅ Live-verified — Playwright e2e 4/4 passing (task 4.4 closed)

Pushed tests/e2e/api-direct/flow-executionmode-and-token.spec.ts + playwright.flow.config.ts.

✓ a sync flow has already run when the triggering request returns   (28.8s)
✓ an async flow is still queued when the triggering request returns (24.3s)
✓ a flow that declares no mode keeps the queued default             (1.1m)
✓ a run persists a flow token through the real database             (17.8s)
  4 passed (3.4m)

The sync/async assertions are timing-free — they compare run state at the instant the create response returns, so they can't flake on worker cadence. The contrast between the first two tests is what actually proves inline execution.

🔴 Live testing caught a real cross-app defect — hermiq#53

The sync test failed at first: the flow ran async anyway, with nothing logged. Root cause was not in this PR:

BEFORE:  HermiqFlowResolver       -> ANSWERS keys=id,nodes,edges,limits      ← wins, wrong owner
         OpenRegisterFlowResolver -> ANSWERS keys=id,nodes,edges,limits,executionMode

HermiqFlowResolver was claiming every flow on the instance, including flows in OpenRegister's own store, because ObjectService::find()'s register/schema arguments do not scope the lookup — a uuid resolves cross-table and returns whatever carries it:

find(id: <OR flow uuid>, register: 'hermiq', schema: 'agentflow')
  -> ObjectEntity(register: 2487, schema: 5077)   // OpenRegister's flow store

Since FlowResolverRegistry takes the first non-null answer, hermiq's over-claim stopped OR's own resolver from ever being asked, and every field hermiq doesn't copy — executionMode, and anything added later — was silently dropped. Fixed in ConductionNL/hermiq#53 (resolver now verifies ownership). After that fix hermiq declines, OR answers, and the e2e goes green.

Worth flagging for a follow-up on this side: ObjectService::find()'s register/schema params look like scoping and behave like hints. Any other caller trusting them has the same latent bug.

Note for reviewers

Every unit test on both sides passed throughout — each app's mocks were internally consistent. Only the live run caught it, which is exactly the "green but dead" class this kind of e2e exists to find.