feat(intent): the glue event axis - process-step events and inbound message/file sources (#6537)

[delchev]

Closes #6537.

The declarative glue bound three event kinds — entity lifecycle, cron, inbound HTTP. Two commonly needed sources were missing, and the issue asks for both, reusing the existing action vocabulary.

1. Process-step events

notifications:
  - name: reviewPending
    event: { onStepReached: { process: LoanApproval, step: librarianReview } }
    to: member.branch.managerEmail
    subject: "Loan {id} is waiting for review"
    body: "A librarian must approve it."

integrations:
  - name: pushActivation
    event: { onStepCompleted: { process: LoanApproval, step: activate } }
    method: POST
    url: "@config:PARTNER_URL"

"Reusing the action vocabulary" is taken literally: no second delivery mechanism is added. BpmnIntentGenerator inserts a generated JavaDelegate at the step's boundary — before the step for reached, after the writer/setter for completed and carrying the step's next so routing cannot be bypassed — which loads the process's trigger entity by the id in the clear-D context and publishes its JSON on the entity's own topic plus a step suffix (-step-<process>-<step>-reached|completed), deferred to after commit so a consumer never sees the record mid-chain. The notification/integration listeners are therefore generated unchanged: every recipient path, {placeholder}, when: guard, attach: print and forwarded body reads exactly as it does for a lifecycle event.

StepEventSupport owns the whole translation (binding → entity → topic suffix → emitter) and deduplicates per (process, step, moment), so ten observers of one moment still publish once. EventBinding stays lifecycle-only.

Rejected at parse, each naming the cause: an unknown process or step; a step kind with no observable moment (only a userTask/serviceTask has one — not a decision, a wait or the end); a process with no trigger (there is then no record the event could be about).

2. Inbound message / file sources

inbound:
  - { name: leadHook,  path: /webhooks/lead, create: Lead }                                  # HTTP (unchanged)
  - { name: leadQueue, source: { queue: leads.inbound }, create: Lead }                      # queue
  - { name: leadFeed,  source: { topic: crm.leads }, create: Lead }                          # topic
  - { name: leadDrop,  source: { folder: /data/inbox/leads, cron: "0 */5 * * * ?" }, create: Lead }  # file

An entry declares exactly one arrival: a path, or a source naming exactly one of queue / topic / folder. What each generates under gen/events/<module>: the existing @Controller webhook; a self-describing MessageHandler (destination()/kind()); a self-describing JobHandler (cron()) polling the drop folder. All three save through the same generated repository — the arrival is a transport, not a second data path, so validations, i18n and the create event fire identically.

The file ingest is specified, not improvised: a file holds one record or an array of them; a file modified inside the stability window is left for the next tick (it may still be being copied in); every read file is moved into processed/ or failed/, so nothing is ingested twice and a rejected file stays inspectable. A folder is polled, not watched — hence the mandatory cron there and its rejection on the other sources.

Kafka/RabbitMQ sources are deliberately out: the platform has no declarative consumer bean for them, and the source: map is open for one when it exists.

Tests

• Unit — GlueStepEventsTest (one emitter per moment; the consumers bound to the step topic of the trigger entity; a lifecycle binding unchanged), StepEventBpmnTest (the emitter's insertion points and routing in the rendered BPMN), GlueInboundSourcesTest (each arrival routed to its own collection with its coordinates), GlueEventAxisIntentTest (every parse rejection of both halves).
• Both layers of the emission contract, in IntentEmissionCoverageIT as the module guide requires: the generated tokens (the emitter wired into the flow, its topic, the consumers binding to that exact topic, the consumer/job shapes), and the published app — a record sent to the declared queue and a batch file dropped into the polled folder both turn into rows over REST, and the step-reached emitter now sits inside the RFQ flow whose task the existing timeout/expire/wait scenarios drive, so a broken emitter fails them.

Verified locally: IntentEmissionCoverageIT green (H2), engine-intent + ide-template unit suites green, formatter:validate and the release-profile javadoc clean.

Docs

In-repo: the assistant guide (intent-assistant-guide.md), the module guide and the root guide. Separately: the vendor-neutral spec (IntentFile/intent-specification#21, IntentFile/intentfile.github.io#21) and dirigible-io/dirigible-io.github.io#184 (merged).