Intent declarative glue: notifications (event → email @Listener)

[delchev]

What

First item of the declarative-glue catalog (see engine-intent/CLAUDE.md → "Planned: declarative glue"): a notifications: block in the intent that sends mail on an entity lifecycle event — generated as an annotated client-Java @Listener, no hand-written code.

notifications:
  - name: orderUpdated
    event: { onUpdate: Order }          # onCreate | onUpdate | onDelete (+ optional when:)
    to: ops@example.com                 # literal address or a direct field of the entity
    subject: "Order {id} updated, total {total}"
    body: "The order changed."

→ generates gen/events/OrderUpdatedNotification.java: an @Listener bound to the entity's …-updated topic that sends via sdk.mail.Mail (sender from DIRIGIBLE_MAIL_SENDER).

How

• Parse + validate (NotificationIntent + IntentParser): unique name; exactly one of onCreate/onUpdate/onDelete on a declared entity; supported channel; recipient present.
• NotificationSupport (pure, unit-tested) translates the author fields into the Java the listener pastes in — recipient (literal or entity.<Field>), {field} interpolation, and a single-comparison when guard.
• GlueIntentGenerator emits a notifications collection into <intent>.glue; Notification.java.template renders the listener; generateUtils.js gets the notifications collection case. Honors the .settings overrides.notifications.<name>.generate=false switch.

Notes / decisions

• The event key is event:, not on: — YAML 1.1 resolves a bare on (also off/yes/no) to boolean true, which silently emptied the binding. IntentEngineIT caught it.
• v1 scope: to/placeholders resolve direct fields or literals; when is a single field ==|!= literal. Relation-path recipients (member.email) are rejected by the parser with a clear message and are the next increment (they reuse the decision-resolver machinery).
• Also restores the "Planned: declarative glue" plan section to CLAUDE.md (it was lost in the Intent Editor: AI assistant (Claude chat + patch preview) #6040 squash merge).

Testing

• NotificationSupportTest — 4 unit tests for the expression translation (green locally).
• IntentEngineIT.glue_template_generates_… extended to assert the generated OrderUpdatedNotification.java (topic, Mail.send, recipient, subject interpolation, lowercased-package import) — green locally (Tests run: 1, Failures: 0). CI runs the full suite on H2/PostgreSQL/MSSQL.

Depends on / relates to

• Builds on the entity update/delete events (PR Publish entity update/delete events from the Java DAO (intent glue foundation) #6049) for the -updated/-deleted topics.
• Uses the same client-Java SDK surface as the merged process triggers (Intent Editor: AI assistant (Claude chat + patch preview) #6040).

🤖 Generated with Claude Code

[delchev]

Update: added one-hop relation.field resolution (commit b7e0480). The "v1 scope" in the description is now broader — to/subject/body resolve a literal, a direct field, or a one-hop relation.field of a to-one relation (the listener loads the related entity once by FK id, reusing the decision-resolver convention). E.g. on an Order event: to: customer.email, subject: "Order for {customer.name}".

Remaining gap: multi-hop paths (a.b.c) and relation-path when: guards — the parser rejects multi-hop to with a clear message. Verified by NotificationSupportTest (5) + IntentEngineIT (the generated listener loads the related Customer and reads customer.Name).