feat(flow)!: a path ends deliberately or says it is broken, and a flow records its last run

[rubenvdlinde]

Closes the silent-success hole in the flow engine, and gives a flow a memory of its own last run.

The defect

A node with no outgoing edge was a silent success. Its token arrived, the step ran, the engine found no enabled transition, the run stopped — and was recorded COMPLETED. Nothing failed, so nothing was logged, and the author saw a green run that had not done the work.

Ending a path is now something a node says

Two ways, OR-ed and never AND-ed:

IFlowTerminalNode	a marker interface on the TYPE, resolved via FlowNodeRegistry::isTerminal(), so a terminal step contributed by openconnector or hermiq needs no OpenRegister change. StopNode implements it.
"exit": true	on the node instance — for a sink whose step type is an ordinary action, which is what every migrated flow has, because that was a legitimate end of a path under the old place-and-edge reading.

Requiring both would make every migrated flow depend on a registry the migration cannot see.

A marker interface rather than a method on IFlowNode, for the reason IFlowNodeConfigKeys already documents: implementations live in other repositories, and widening the interface fatals those apps on load.

Warn on save, refuse on run

Saving succeeds and warns. A disconnected graph is the normal state of one being authored; refusing to store it would force the author to build the graph in an order that is never disconnected, which no editor can require.

Running is refused, and the guard sits in FlowRunService::queue() — the one choke point every dispatch path passes through: manual, trigger, schedule, MCP, the workflow-engine operation, and a sub-flow call. Guarding FlowService::run() alone would have left cron-fired flows unguarded, and those are most of them.

On refusal no FlowRun is created, so the verdict is written onto the flow (status / statusMessage, naming the nodes). That is exactly what makes a refused flow distinguishable from one nobody has triggered — there is no run to read. An accepted run clears a stale error back to ok.

The schedule sweep catches the refusal per flow: it iterates every due flow, so letting it propagate would abort the sweep and stop every later flow from firing — one broken definition silently disabling the rest, presenting as "cron stopped working" rather than as a fault in a named flow.

A typeless node is deliberately not reported here — FlowDefinitionBuilder already refuses it by name, and two findings on one node for one defect is how a warning list becomes noise.

Last run

Six nullable columns, no backfill. A null lastRunAt means "has never run"; a value derived from run history would assert a history the column did not record. Written only when a run reaches a terminal state, so the list answers "how did it last go?" rather than "it hasn't finished".

Also

Adds the canonical openspec/specs/flow-engine/spec.md. It did not exist — the flow-engine spec lived only inside changes/ — so @spec had nowhere canonical to point.

What is NOT done

Stated in tasks.md rather than quietly skipped: the schedule/trigger dispatch wiring and the last-run write-back are not yet pinned by tests. Both need FlowRunService built with a mocked container, mapper and preflight. The connectivity verdict they consume is covered, each assertion with a positive control proving the same graph goes quiet once wired.

Verification honesty

The unit suite could not be run locally. Once lib/base.php loads, Nextcloud's autoloader resolves OCA\OpenRegister\* to the installed app, not the working copy — measured with ReflectionClass::getFileName(). CI's "copy the app out of /var/www/html" step does not prevent this; CI is immune only because it deploys the code under test first, making both copies identical. Run that recipe locally against an older deployment and the suite reports on the deployed app — a green that says nothing. CI is the authoritative gate for this change.

Breaking

A flow with a dead-ended node is now refused at run time instead of completing silently. Mark deliberate sinks "exit": true, or give them a terminal step type.

[github-actions]

Quality Report — ConductionNL/openregister @ 1345887

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	❌
psalm	❌
phpstan	❌
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
check-specs		✅
test-l10n		✅
composer			✅	✅ 173/173
npm			✅	✅ 713/713
PHPUnit					❌
Newman					✅
Playwright					✅
Hydra gates					❌

---

Quality workflow — 2026-08-05 20:18 UTC

Download the full PDF report from the workflow artifacts.

[github-actions]

Quality Report — ConductionNL/openregister @ 68baa6f

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	❌
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
check-specs		✅
test-l10n		✅
composer			✅	✅ 173/173
npm			✅	✅ 713/713
PHPUnit					❌
Newman					✅
Playwright					✅
Hydra gates					❌

---

Quality workflow — 2026-08-05 21:06 UTC

Download the full PDF report from the workflow artifacts.

[github-actions]

Quality Report — ConductionNL/openregister @ 95bfb10

Check	PHP	Vue	Security	License	Tests
lint	✅
phpcs	✅
phpmd	✅
psalm	✅
phpstan	✅
phpmetrics	✅
eslint		✅
stylelint		✅
build		✅
check-specs		✅
test-l10n		✅
composer			✅	✅ 173/173
npm			✅	✅ 713/713
PHPUnit					✅
Newman					✅
Playwright					✅
Hydra gates					✅

---

Quality workflow — 2026-08-05 21:31 UTC

Download the full PDF report from the workflow artifacts.