[OpenSpec] case-flow-human-steps

[github-actions]

⚠️ OpenSpec-managed issue — this content is automatically synced
from the openspec/ directory. Manual edits will be overwritten on next sync.

Artifacts

• ✅ Metadata
• ✅ Proposal
• ✅ Specs
• ✅ Design
• ✅ Tasks
• 🔲 Plan
• 🔲 Review

Specs

• 📄 case-flow-human-steps
• 📄 status-transition-engine
• 📄 task-management

Tasks

• 1.1 Add flowRun and flowNode to the task schema in lib/Settings/dossiq_register.json; verify a task round-trips both through the object store and that existing tasks (both null) still save
• 1.2 Add the six status types and the omgevingsvergunning-kleinbouw case type to the seed data; verify the seed imports and the status types resolve from the case type
• 2.1 Declare the case-behandeling flow as x-openregister-flows on the case schema: trigger on create, status steps, completeness switch, applicant-task loop, two decisions, employee task, commission decision, document, close; verify it imports into the flow store
• 2.2 Verify the shipped flow arrives DISABLED and ownerless, and that re-importing the register updates it rather than creating a second copy
• 2.3 Verify the completeness loop's three exits (complete / under cap / at cap) and that the at-cap exit moves the case to gestrand and ends the run without hitting the engine's transition ceiling
• 3.1 Make the applicant-ask step create a task stamped with the run and node, then suspend; verify the task names the case and what is missing, and the run's status is suspended
• 3.2 Implement task completion → FlowRunService::signal() in a TaskCompletionService; verify the run resumes at the node that asked and the outcome reaches the following steps
• 3.3 🔴 Verify the AUTHORIZATION refusal: a user who is neither the assignee nor in the assigned group cannot complete the task, and therefore cannot resume the run — this test must fail if the check is removed, since the direct service call bypasses refuseUnlessAssignee()
• 3.4 Verify the three degenerate completions: a task with no run resumes nothing and raises no error, completing twice resumes once, and a task whose run no longer exists still completes
• 4.1 Add DossiqRequestDecisionNode raising the decision through AdviceDelegationService, storing the decisionRef and suspending; verify the run suspends and the ref is on the case
• 4.2 Resume the waiting run from DecisionConcludedListener, matched on decisionRef; verify the concluded decision resumes it and an UNRELATED decision leaves it suspended
• 4.3 Verify the fail-closed path: with decidiq unavailable the step fails and the run does not advance past the decision
• 5.1 Generate the decision document from the template and attach it to the case after final approval; verify it is attached before the case reaches its final status
• 5.2 Verify a failed generation leaves the case OPEN with the failure recorded, and that a rejection closes the case with a rejection document
• 6.1 Show both halves of the waiting relationship — on a task, that a case is waiting on it (linking to the case); on the case detail, its flow run and current stage; verify a non-flow task and a case with no run both render unchanged and without error
• 7.1 Playwright journey over the incomplete case: intake → applicant task → complete it → the case advances and its status changes; verify against the status the applicant sees, not against internal state
• 7.2 Playwright journey over the happy path: complete case → two decisions → employee task → commission approval → document attached → case closed
• 7.3 Verify the traceability read: after the journey, the run reports the objects it touched grouped by node, and the case's history names the node that moved each status
• 8.1 Run composer check:strict and npm run lint, fixing pre-existing findings in the files touched
• 8.2 Mutation-check the authorization guard from 3.3: remove it, confirm the suite goes red, restore, confirm the source is byte-identical

Design

See design.md for technical design details.

---

Synced from openspec/changes/case-flow-human-steps by OpenSpec workflow
App: dossiq

[rubenvdlinde]

Heads-up: the E2E specs added in 605a6a2 are failing on development — 5 failed / 130 passed, bracketed to that single commit (last green 66d45d2a, first red 605a6a22).

✘ case-flow-human-steps.spec.ts:59   the shipped flow imports, and imports INERT       (535ms)
✘ case-flow-human-steps.spec.ts:117  the case type ships every status the flow moves to (19.5s)

The assertion message states the two candidates itself:

Error: The case flow was not found in the flow store. It is declared as
x-openregister-flows on the case schema, so its absence means the register
import did not run or the declaration was rejected.

expect(received).not.toBeNull()
Received: null

What I could confirm

The declaration is present and parses. In lib/Settings/dossiq_register.json, at /components/schemas/case:

"x-openregister-flows": [
  { "name": "Case behandeling", "app": "dossiq", "description": "Walks a case from intake to closure: …" }
]

So it is not a missing declaration. That leaves the import did not run or the declaration was rejected, and I could not separate those from the job log — no flow-import error surfaces in the E2E job output, so whatever rejected it (if anything) is not being reported where CI can see it.

Why I am not guessing at a fix

Telling those two apart needs OpenRegister-side knowledge of what makes an x-openregister-flows entry valid — a missing required key, an unknown node type, an app-scope mismatch. Any of those would be invisible in the JSON and obvious to whoever wrote the importer.

Worth noting either way: if the declaration was rejected, the rejection is silent. A register import that drops a flow without saying so is its own defect, independent of this one — the spec had to infer it from an empty store.

Flagged rather than fixed because this is 40-minute-old feature work and the fix belongs with its author. Everything else on dossiq's development is green (130 passing).

[rubenvdlinde]

Narrowed down: the flow import is event-driven, so it only runs if the import dispatches the event

Still failing at 6687404e (the 21:11 fix took it from 5 failures to 1, but this one remains):

✘ case-flow-human-steps.spec.ts:59  the shipped flow imports, and imports INERT  (501ms)
   The case flow was not found in the flow store.
1 failed / 135 passed

Earlier I could only say "the import did not run, or the declaration was rejected". Here is the missing half.

OpenRegister imports these flows from a LISTENER

lib/Listener/SchemaFlowImportListener.php, registered in Application.php:

$context->registerEventListener(SchemaCreatedEvent::class, SchemaFlowImportListener::class);
$context->registerEventListener(SchemaUpdatedEvent::class, SchemaFlowImportListener::class);

So x-openregister-flows is not read during a generic register import. It is read when a schema is created or updated through a path that dispatches SchemaCreatedEvent / SchemaUpdatedEvent.

That makes the question concrete and answerable without guessing:

Does dossiq's CI register import create its schemas via the service that dispatches those events, or does it write them by a route that bypasses the dispatch?

If it bypasses, the listener never fires, the flow is never imported, and the store is legitimately empty — with no error anywhere, which matches exactly what the job log shows (I checked: no flow-import error is emitted at all).

Why this shape is worth ruling out first

A registered listener that never receives its event is indistinguishable from a missing feature: the class exists, the declaration is valid, nothing errors, and the result is simply absent. The cheapest check is whether SchemaCreatedEvent fires at all during the seed — if it does not, that is the whole answer.

Confirmed on my side: the declaration is present and well-formed at /components/schemas/case in dossiq_register.json, OpenRegister on development does implement the listener, and dossiq's CI installs openregister from development — so neither the declaration nor a version gap explains it.

Everything else on dossiq is green (135 passing).

[rubenvdlinde]

Correction: I was wrong — the import DOES dispatch the event

My previous comment suggested the register import might bypass SchemaCreatedEvent, leaving SchemaFlowImportListener unfired. That is not the case. I traced the whole path and it is intact:

dossiq SettingsController::load()
  -> SettingsService::loadConfiguration(force: true)
    -> OpenRegister ConfigurationService
      -> Configuration\ImportHandler
        -> SchemaMapper::createFromArray()      (ImportHandler.php:1912)
             -> $this->insert(entity: $schema)  (SchemaMapper.php, inside createFromArray)
                  -> dispatchTyped(new SchemaCreatedEvent(...))   (SchemaMapper.php:1017)

        -> SchemaMapper::updateFromArray() / update()  (ImportHandler.php:1899, 1908)
                  -> dispatchTyped(new SchemaUpdatedEvent(...))   (SchemaMapper.php:1987)

Both branches — new schema and existing schema — go through a dispatching method. So the event fires and the listener is reached. Please disregard the "bypasses the dispatch" theory; chasing it would have wasted your time.

What that leaves

Since the declaration is valid, the version is current, and the event does fire, the remaining candidates are narrower:

1. The listener runs and rejects the declaration — some field it requires is absent or shaped differently than it expects. It would need to log that; nothing appears in the job output, so if it rejects, it does so silently.
2. The listener runs and imports somewhere the test does not look — a scoping mismatch (app, register, or multitenancy) between where the flow is written and where case-flow-human-steps.spec.ts queries.
3. The import is idempotent and short-circuits — if the schema is unchanged from a previous import, updateFromArray may return early without reaching update(), so no event fires on that path. Worth checking whether the very first import on a clean CI instance behaves differently from a re-run.

(3) is the one I would test first, because it fits the symptom: the seed reports success, no error appears anywhere, and the flow store is simply empty.

One thing worth fixing regardless

ConfigurationService injects SchemaMapper, assigns it in the constructor, and never calls it — zero call sites in 988 lines. Harmless today since the real work moved to ImportHandler, but it is exactly the unused-injected-dependency shape hydra-gates' stub-scan flags, and it made this trace considerably harder to follow than it needed to be.

[rubenvdlinde]

The entire static path is intact — so this is runtime, not structure

I traced every link between the declaration and the listener. All five hold:

#	link	evidence
1	declaration present at the schema root	dossiq_register.json → /components/schemas/case → x-openregister-flows, one entry, well-formed
2	root-level x-openregister-* folded into configuration	Schema::hydrate() — "Fold top-level x-openregister-* annotation blocks … into the configuration array", str_starts_with($key, 'x-openregister-')
3	setConfiguration() keeps the key	x-openregister-flows is in the allowlist (Schema.php:2430) — the file's own comment notes an absent key is "silently DROPPED"
4	the write dispatches	ImportHandler → createFromArray → insert() → SchemaCreatedEvent; updateFromArray → update() → SchemaUpdatedEvent, unconditionally — no idempotent short-circuit
5	the listener is registered for both	Application.php:2541-2542
6	the listener reads that exact key	SchemaFlowImportListener::importFor() → getConfiguration()['x-openregister-flows']

So all three of my earlier theories are dead: the import does not bypass the dispatch, it does not short-circuit when unchanged, and the key is not dropped by the allowlist. Sorry for the noise — recording them as eliminated so nobody re-walks them.

What is left

The failure is therefore in runtime behaviour, not wiring:

• the listener throws and the exception is swallowed — its own docblock says a failing declaration is "logged and SKIPPED rather than aborting the rest", so a malformed entry disappears quietly. Check the Nextcloud log, not the CI job output — that is where such a log line would go, and it is not in the job log at all.
• or the flow is written under a scope (app, register, or tenancy) that case-flow-human-steps.spec.ts:59 does not query.

The first is cheap to test: occ log:tail while forcing a re-import, or grep the instance log for the listener's own failure message.

Separately, worth a look

ConfigurationService injects SchemaMapper, assigns it in the constructor, and never calls it — zero call sites in 988 lines. Dead since the work moved to ImportHandler. It is the unused-injected-dependency shape hydra-gates' stub-scan targets, and it cost me a detour during this trace.

[rubenvdlinde]

The instance log rules out silent rejection — the listener produced no output at all

I said the decisive check was the Nextcloud log rather than the CI job output. It turns out CI does capture it: the nextcloud-log-e2e artifact on the failing run (33211479033), 4,337 entries.

[SchemaFlowImport] appears zero times.

That matters because the listener logs on both outcomes:

'[SchemaFlowImport] Imported declared flow "'          (info, on success)
'[SchemaFlowImport] Could not import a declared flow'  (warning, on a bad declaration)
'[SchemaFlowImport] Could not resolve an organisation' (warning, imports but unlisted)

No line of any kind means it never reached any of them. So "the listener rejected the declaration silently" is dead — a rejection would have logged a warning. The only path that produces total silence is the early return:

$declared = (($schema->getConfiguration() ?? [])[self::ANNOTATION_KEY] ?? null);
if (is_array($declared) === false || $declared === []) {
    return;   // no log
}

So at the moment the listener ran, configuration['x-openregister-flows'] was absent or empty — or the listener never ran at all. Those two are now the entire remaining space.

What the log does show about case

Annotations on this very schema are being validated and rejected, just a different one:

x-openregister-lifecycle annotation on schema "case" is invalid and was ignored
(no status workflow applied): x-openregister-lifecycle is missing requ…

So case's annotations are reaching validation, and at least one is being dropped for being malformed. Whether the flows annotation survives the same pass is the obvious next question, and that log line is the thread to pull.

Ruled out by reading the code (recorded so nobody re-walks them)

• hydrate() folds top-level x-openregister-* into configuration — it does
• setConfiguration() allowlist — x-openregister-flows is present (Schema.php:2430)
• cleanObject() — only ensures UUID and slug
• extractSchemaDelta() — operates on properties for inheritance, not configuration
• the dispatch — insert()/update() fire unconditionally, no idempotent short-circuit

Everything structural checks out, which is why the answer is in that log line rather than in the wiring.

[rubenvdlinde]

Seven hypotheses eliminated, plus live-instance evidence

I had access to a running dev instance (Nextcloud 34, openregister + dossiq enabled) and traced the rest of the path against it.

Measured on the live instance

schemas total:                                        1413
schemas whose configuration carries x-openregister-flows: 0
openregister_flows rows:                               193

The case schema there does carry seven other annotations in configuration — x-openregister-processing, -references, -calculations, -lifecycle, -notifications, -archival, -quality, -dedup — proving hydrate()'s fold of top-level x-openregister-* keys works in practice. x-openregister-flows is simply absent.

⚠️ That instance's dossiq predates the declaration (grep -c x-openregister-flows → 0 on its copy), so it cannot reproduce your failure — it has nothing to import. It is evidence about the mechanism, not about your commit. Worth stating plainly so nobody reads more into it.

Notably: 193 flows exist there, all created by other routes. Zero schemas anywhere carry the annotation, which suggests dossiq's is the first one ever shipped through this path.

Eliminated, with the evidence

#	hypothesis	verdict
1	import bypasses the dispatch	createFromArray → insert() → SchemaCreatedEvent
2	idempotent import short-circuits	updateFromArray calls update() unconditionally
3	setConfiguration() allowlist drops it	present, Schema.php:2430
4	cleanObject / extractSchemaDelta strip it	UUID+slug, and property-inheritance only
5	listener rejects it silently	it catches Throwable and logs a warning — the instance log has zero [SchemaFlowImport] entries of any kind
6	a register.d fragment overwrites case	dso-omgevingsloket.json does redefine case, but RegisterFragmentMerger::deepMerge() recurses into associative arrays, so properties merges into the monolith and the annotation survives
7	the version/content skip in ImportHandler	x-openregister-flows is in Schema::ANNOTATION_VOCABULARY, so schemaAnnotationsDiffer() sees the change; and the seeder posts force: true, which disables the version gate anyway

What that leaves

The static path is correct end to end. The remaining candidates are environmental or ordering:

• the schema import ran against a deployment that did not yet contain the declaration (worth checking the CI job's checkout order versus when the import POST fires)
• the flow imports under an organisation/scope the spec's lookup does not cover — the listener has an explicit "could not resolve an organisation … it will import but stay unlisted" path, and an unlisted flow may be invisible to the query

The second is cheap to test: query the flow store without the organisation/app filter the spec uses and see whether the row exists but is unlisted.

[rubenvdlinde]

Reproduced on a live instance — the import chain WORKS

I got access to a running instance (Nextcloud 34, openregister + dossiq) and drove the real path end to end.

POST /index.php/apps/dossiq/api/settings/load   -> HTTP 200, 109 schemas mapped

openregister_flows:
  id=257  app=dossiq  name="Case behandeling"  enabled=false

enabled=false is exactly the state case-flow-human-steps.spec.ts:59 asserts ("the shipped flow imports, and imports INERT"). On this instance that test would pass.

So every link works in practice, not just on paper:

dossiq_register.json  x-openregister-flows on /components/schemas/case
  -> hydrate() folds it into `configuration`
  -> setConfiguration() keeps it (allowlisted)
  -> insert()/update() dispatches SchemaCreated/UpdatedEvent
  -> SchemaFlowImportListener imports it, disabled and unowned

This is not a code defect in the import chain. Combined with the seven hypotheses already eliminated by reading the source, the failure has to be environmental to CI.

Where I would look now

1. Ordering. Does the CI seed POST settings/load after the app code carrying the declaration is in place? If the import fires against an older checkout, the declaration is not there to read — and nothing errors, which matches the total absence of [SchemaFlowImport] log lines in the CI run's nextcloud-log-e2e artifact.
2. Scope. The listener has an explicit "could not resolve an organisation … it will import but stay unlisted" path. Query the flow store without the spec's app/organisation filter; if the row exists but is unlisted, that is the whole bug.

(1) fits the evidence best: on CI the listener logged nothing at all, and the only silent path is the declaration being absent from configuration when the event fired.

One correction to my earlier comments

I previously reported that the instance's dossiq copy contained zero occurrences of x-openregister-flows. That reading was of a stale copy — the environment pulled dossiq's update during my session, and the declaration is present at line 1028 of the register. Anything I inferred from that zero should be disregarded; the measurements above are from the current code.