Workflow definition versioning: pin running instances to a version (#3604588)

Frank Mablyrequested to merge
issue/orchestra-3604588:feature/workflow-versioning into 1.x

Implements Phase 1 of #3604588: a running instance is pinned to the workflow definition it started on, so editing a workflow no longer changes (or breaks) instances already running on it.

What changed

  • WorkflowDefinitionInterface: the read contract (nodes, flows, start node, tenant scoping) the engine executes against, implemented by both the editable Workflow config entity (via a shared WorkflowDefinitionTrait) and an immutable version snapshot.
  • orchestra_workflow_version: a revisionable content entity, one per workflow; each distinct executed definition is a revision, and the revision id is the version. It stores the executable definition (tenant, start node, nodes, flows), not the diagram layout.
  • ProcessInstance.definition_version: the pinned revision id, stamped at start. Legacy instances (NULL) fall back to the live config, so the change is non-breaking.
  • WorkflowVersionManager: resolves the version to pin behind a cached workflow -> version pointer (so start stays O(1)); snapshots lazily, deduped by an executable hash, under a lock; reads pinned versions back (immutable, so cached); invalidates the pointer on workflow save.
  • Engine: start() pins a version; definitionFor() resolves an instance's pinned snapshot (live fallback); internal read methods now take WorkflowDefinitionInterface.

Versioning mode (config select, default Automatic)

  • Off: never pin; instances run the live config.
  • Automatic: editing a workflow versions it on the next start (deduped by hash).
  • Manual: instances run the last published version; publish() adopts an edit. The first start bootstraps one.

The diagram layout is excluded from the hash, so a layout-only save creates no version.

Tests

WorkflowVersioningTest covers pin/reuse, edit-under-running-instance safety (deleting the parked node from the live workflow, the pinned instance still completes), legacy fallback, and the three modes. The engine kernel tests install the new schema; the full core + cm + inbox kernel suites pass (149 tests).

Docs and i18n

docs/versioning.md (+ nav); French translations for the new UI strings.

Migration (pre-1.0)

No update hook. On an existing site the new entity and the instance field are installed via the throwaway entity-definition update (done on the maintainer's live site); pre-existing running instances stay on the live-config fallback until migrated.

Follow-ups (later phases, per the issue)

Version UI (per-workflow version list + running-instance counts), migration tooling, and a Publish button for manual mode (the engine/manager already support publishing).

Merge request reports