feat(messaging): notify baseline node + lean service-messaging vertical slice (ADR-0012) (#1420)

Make the `notify` flow node a real capability instead of a no-op, backed by a
minimal, ADR-0012-aligned messaging vertical slice.

Spec
- flow.zod.ts: add `notify` to the builtin flow-node action enum (+ test).

service-messaging (new @objectstack/service-messaging)
- MessagingChannel seam (channel.ts): Notification/Delivery/SendResult +
  MessagingChannel interface (id, send, optional classifyError).
- MessagingService (registry + emit): register/unregister/get channels; emit
  defaults channels to ['inbox'], fans out per (channel × recipient), isolates
  a throwing/failing/unregistered channel into a failed delivery — never throws.
- Always-on inbox channel: writes sys_inbox_message rows via the data engine;
  degrades to a logged no-op when no data engine is present.
- sys_inbox_message object + MessagingServicePlugin (registers the `messaging`
  service, the inbox channel, and the object via the manifest).

service-automation
- notify-node.ts: baseline `notify` io node. Interpolates recipients/title/body/
  channels/topic/severity/actionUrl/payload; resolves the `messaging` service
  through a local structural surface (no runtime dep on service-messaging,
  mirroring ConnectorRegistrySurface). Degrades to a logged success when no
  messaging service is installed; emits otherwise. Wired into installBuiltinNodes.

Example
- app-showcase: TaskAssignedNotifyFlow — worked `notify` example (inbox channel).

Deferred to follow-ups (per chosen minimal-slice scope): email/push/webhook
channels, topic↔preference matrix, outbox/retry extraction.

Tests: service-messaging 19, service-automation 95, spec + runtime green.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>

Author: xuyushun441-sys

examples/app-showcase/src/flows/index.ts

@@ -89,6 +89,56 @@ export const ReassignWizardFlow = defineFlow({
   ],
 });
 
+/**
+ * Task Assigned → Notify Assignee — the worked `notify` example (ADR-0012).
+ *
+ * Where {@link TaskCompletedFlow} hand-waves notification through a `script`
+ * node, this flow uses the baseline `notify` node: it hands a topic +
+ * recipient + message to the messaging service, which fans out to the user's
+ * channels (inbox by default). The `notify` node ships in every automation
+ * engine; delivery is backed by `@objectstack/service-messaging`
+ * (`MessagingServicePlugin`). Without that plugin the node degrades to a
+ * logged no-op instead of failing the flow — install it and this flow starts
+ * landing inbox rows with no edit.
+ */
+export const TaskAssignedNotifyFlow = defineFlow({
+  name: 'showcase_task_assigned_notify',
+  label: 'Notify Assignee on Task Assignment',
+  description: 'Notifies the new assignee (inbox channel) when a task is reassigned.',
+  type: 'autolaunched',
+  nodes: [
+    {
+      id: 'start',
+      type: 'start',
+      label: 'On Task Assignee Change',
+      config: {
+        objectName: 'showcase_task',
+        triggerType: 'record-after-update',
+        condition: 'assignee != previous.assignee',
+      },
+    },
+    {
+      id: 'notify_assignee',
+      type: 'notify',
+      label: 'Notify Assignee',
+      config: {
+        topic: 'task.assigned',
+        recipients: ['{record.assignee}'],
+        channels: ['inbox'],
+        severity: 'info',
+        title: 'New task assigned: {record.title}',
+        message: 'You have been assigned "{record.title}".',
+        actionUrl: '/showcase_task/{record.id}',
+      },
+    },
+    { id: 'end', type: 'end', label: 'End' },
+  ],
+  edges: [
+    { id: 'e1', source: 'start', target: 'notify_assignee' },
+    { id: 'e2', source: 'notify_assignee', target: 'end' },
+  ],
+});
+
 /**
  * Project Budget Approval — ADR-0019 approval-as-flow-node.
  *
@@ -213,4 +263,5 @@ export const allFlows = [
   ReassignWizardFlow,
   BudgetApprovalFlow,
   TaskCompletedSlackFlow,
+  TaskAssignedNotifyFlow,
 ];

packages/services/service-automation/src/builtin/index.ts

@@ -15,6 +15,7 @@
  *  - human   — screen / script                   (core flow capability)
  *  - io      — http_request                       (foundational outbound I/O)
  *  - io      — connector_action                   (generic integration dispatch)
+ *  - io      — notify                              (outbound notification via messaging service)
  *
  * `connector_action` is the *generic dispatch* counterpart to `http_request`
  * (ADR-0018 §Addendum): the platform ships the node + an (initially empty)
@@ -31,12 +32,14 @@ import { registerCrudNodes } from './crud-nodes.js';
 import { registerScreenNodes } from './screen-nodes.js';
 import { registerHttpNodes } from './http-nodes.js';
 import { registerConnectorNodes } from './connector-nodes.js';
+import { registerNotifyNode } from './notify-node.js';
 
 export { registerLogicNodes } from './logic-nodes.js';
 export { registerCrudNodes } from './crud-nodes.js';
 export { registerScreenNodes } from './screen-nodes.js';
 export { registerHttpNodes } from './http-nodes.js';
 export { registerConnectorNodes } from './connector-nodes.js';
+export { registerNotifyNode } from './notify-node.js';
 
 /**
  * Seed every built-in node executor into the engine. Called by
@@ -49,6 +52,7 @@ export function installBuiltinNodes(engine: AutomationEngine, ctx: PluginContext
     registerScreenNodes(engine, ctx);
     registerHttpNodes(engine, ctx);
     registerConnectorNodes(engine, ctx);
+    registerNotifyNode(engine, ctx);
 
     const types = engine.getRegisteredNodeTypes();
     ctx.logger.info(

packages/services/service-automation/src/builtin/notify-node.test.ts

@@ -0,0 +1,156 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { AutomationEngine } from '../engine.js';
+import { registerNotifyNode } from './notify-node.js';
+import type { MessagingServiceSurface } from './notify-node.js';
+
+function createTestLogger() {
+    return {
+        info: () => {},
+        warn: () => {},
+        error: () => {},
+        debug: () => {},
+        child: () => createTestLogger(),
+    } as any;
+}
+
+/**
+ * A PluginContext stub whose `messaging` service can be toggled on/off, so we
+ * exercise both the wired path and the degrade-when-absent path.
+ */
+function createCtx(messaging?: MessagingServiceSurface) {
+    return {
+        logger: createTestLogger(),
+        getService(name: string) {
+            if (name === 'messaging') return messaging;
+            return undefined;
+        },
+    } as any;
+}
+
+/** A fake messaging service capturing emitted notifications. */
+function fakeMessaging() {
+    const emitted: any[] = [];
+    const service: MessagingServiceSurface = {
+        async emit(n) {
+            emitted.push(n);
+            return { delivered: n.recipients.length, failed: 0 };
+        },
+    };
+    return { service, emitted };
+}
+
+function notifyFlow(config: Record<string, unknown>) {
+    return {
+        name: 'notify_flow',
+        label: 'Notify Flow',
+        type: 'autolaunched' as const,
+        variables: [
+            { name: 'dealName', type: 'text' as const, isInput: true },
+            { name: 'dealId', type: 'text' as const, isInput: true },
+            { name: 'notify.delivered', type: 'number' as const, isOutput: true },
+        ],
+        nodes: [
+            { id: 'start', type: 'start' as const, label: 'Start' },
+            { id: 'notify', type: 'notify' as const, label: 'Notify', config },
+            { id: 'end', type: 'end' as const, label: 'End' },
+        ],
+        edges: [
+            { id: 'e1', source: 'start', target: 'notify' },
+            { id: 'e2', source: 'notify', target: 'end' },
+        ],
+    };
+}
+
+describe('notify (baseline node)', () => {
+    it('publishes a builtin io descriptor in the action registry', () => {
+        const engine = new AutomationEngine(createTestLogger());
+        registerNotifyNode(engine, createCtx());
+        expect(engine.getRegisteredNodeTypes()).toContain('notify');
+        const descriptor = engine.getActionDescriptor('notify');
+        expect(descriptor?.source).toBe('builtin');
+        expect(descriptor?.category).toBe('io');
+        expect(descriptor?.paradigms).toEqual(
+            expect.arrayContaining(['flow', 'workflow_rule', 'approval']),
+        );
+    });
+
+    describe('with a messaging service registered', () => {
+        let engine: AutomationEngine;
+        let messaging: ReturnType<typeof fakeMessaging>;
+
+        beforeEach(() => {
+            messaging = fakeMessaging();
+            engine = new AutomationEngine(createTestLogger());
+            registerNotifyNode(engine, createCtx(messaging.service));
+        });
+
+        it('emits a notification, interpolating recipients/title/body, and reports delivered count', async () => {
+            engine.registerFlow('notify_flow', notifyFlow({
+                topic: 'deal.won',
+                recipients: ['user_1', 'user_2'],
+                title: 'Deal {dealName} closed',
+                message: 'Congrats on {dealName}',
+                channels: ['inbox', 'email'],
+                severity: 'info',
+                actionUrl: '/opps/{dealId}',
+            }));
+
+            const result = await engine.execute('notify_flow', {
+                params: { dealName: 'Acme', dealId: '42' },
+            } as any);
+
+            expect(result.success).toBe(true);
+            expect(messaging.emitted).toHaveLength(1);
+            expect(messaging.emitted[0]).toMatchObject({
+                topic: 'deal.won',
+                title: 'Deal Acme closed',
+                body: 'Congrats on Acme',
+                recipients: ['user_1', 'user_2'],
+                channels: ['inbox', 'email'],
+                severity: 'info',
+                actionUrl: '/opps/42',
+            });
+            expect(result.output).toMatchObject({ 'notify.delivered': 2 });
+        });
+
+        it('accepts a single recipient string and the subject/to aliases', async () => {
+            engine.registerFlow('notify_flow', notifyFlow({
+                to: 'user_9',
+                subject: 'Heads up',
+            }));
+            const result = await engine.execute('notify_flow');
+            expect(result.success).toBe(true);
+            expect(messaging.emitted[0]).toMatchObject({ title: 'Heads up', recipients: ['user_9'] });
+        });
+
+        it('fails the step when title is missing', async () => {
+            engine.registerFlow('notify_flow', notifyFlow({ recipients: ['user_1'] }));
+            const result = await engine.execute('notify_flow');
+            expect(result.success).toBe(false);
+            expect(result.error).toContain('title');
+        });
+
+        it('fails the step when no recipient is given', async () => {
+            engine.registerFlow('notify_flow', notifyFlow({ title: 'Hi' }));
+            const result = await engine.execute('notify_flow');
+            expect(result.success).toBe(false);
+            expect(result.error).toContain('recipient');
+        });
+    });
+
+    describe('without a messaging service', () => {
+        it('degrades to a no-op success (skipped) rather than failing the flow', async () => {
+            const engine = new AutomationEngine(createTestLogger());
+            registerNotifyNode(engine, createCtx(undefined));
+            engine.registerFlow('notify_flow', notifyFlow({
+                recipients: ['user_1'],
+                title: 'Hi',
+            }));
+
+            const result = await engine.execute('notify_flow');
+            expect(result.success).toBe(true);
+        });
+    });
+});

packages/services/service-automation/src/builtin/notify-node.ts

@@ -0,0 +1,123 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { PluginContext } from '@objectstack/core';
+import { defineActionDescriptor } from '@objectstack/spec/automation';
+import type { AutomationEngine } from '../engine.js';
+import { interpolate } from './template.js';
+
+/**
+ * Structural view of `@objectstack/service-messaging`'s service (ADR-0012),
+ * declared locally so service-automation does not take a runtime dependency on
+ * it — mirrors the `ConnectorRegistrySurface` pattern. The `notify` node
+ * resolves whatever object is registered under the `messaging` service and
+ * dispatches through this shape; if no such service is present the node
+ * degrades to a no-op success.
+ */
+export interface MessagingServiceSurface {
+    emit(notification: {
+        topic?: string;
+        title: string;
+        body: string;
+        severity?: string;
+        recipients: string[];
+        channels?: string[];
+        actionUrl?: string;
+        payload?: Record<string, unknown>;
+    }): Promise<{ delivered: number; failed: number }>;
+}
+
+/** Coerce a config value (string | string[]) into a clean string[]. */
+function toStringList(value: unknown): string[] {
+    if (Array.isArray(value)) return value.map((v) => String(v)).filter(Boolean);
+    if (typeof value === 'string' && value.trim()) return [value.trim()];
+    return [];
+}
+
+/**
+ * `notify` built-in node (ADR-0012) — outbound notification.
+ *
+ * Baseline node and the human-notification counterpart to `http_request`
+ * ("raw call") and `connector_action` ("call a registered integration"):
+ * `notify` hands a topic + recipients + message to the platform's messaging
+ * service, which fans it out across the user's channels (inbox by default).
+ *
+ * Like the CRUD nodes degrade without a data engine, `notify` degrades to a
+ * warning + success when no `messaging` service is registered — the capability
+ * simply isn't installed in that stack. Install `MessagingServicePlugin`
+ * (`@objectstack/service-messaging`) and the same flow starts delivering, with
+ * no flow edit. This is the seam that fixes the "notify drops on the floor"
+ * gap (#1292) once messaging is present.
+ */
+export function registerNotifyNode(engine: AutomationEngine, ctx: PluginContext): void {
+    const getMessaging = (): MessagingServiceSurface | undefined => {
+        try {
+            return ctx.getService<MessagingServiceSurface>('messaging');
+        } catch {
+            return undefined;
+        }
+    };
+
+    engine.registerNodeExecutor({
+        type: 'notify',
+        descriptor: defineActionDescriptor({
+            type: 'notify', version: '1.0.0', name: 'Notify',
+            description: 'Send an outbound notification to users via the messaging service (inbox / email / push / …).',
+            icon: 'bell', category: 'io', source: 'builtin',
+            supportsRetry: true,
+            paradigms: ['flow', 'workflow_rule', 'approval'],
+        }),
+        async execute(node, variables, context) {
+            const cfg = (node.config ?? {}) as Record<string, unknown>;
+
+            const recipients = toStringList(interpolate(cfg.recipients ?? cfg.to ?? [], variables, context));
+            const title = String(interpolate(cfg.title ?? cfg.subject ?? '', variables, context) ?? '');
+            const body = String(interpolate(cfg.message ?? cfg.body ?? '', variables, context) ?? '');
+            const channels = toStringList(cfg.channels);
+            const topic = cfg.topic ? String(cfg.topic) : undefined;
+            const severity = cfg.severity ? String(cfg.severity) : undefined;
+            const actionUrl = cfg.actionUrl
+                ? String(interpolate(cfg.actionUrl, variables, context) ?? '')
+                : undefined;
+            const payload = cfg.payload
+                ? (interpolate(cfg.payload, variables, context) as Record<string, unknown>)
+                : undefined;
+
+            if (!title) return { success: false, error: 'notify: title (or subject) is required' };
+            if (recipients.length === 0) {
+                return { success: false, error: 'notify: at least one recipient is required' };
+            }
+
+            const messaging = getMessaging();
+            if (!messaging) {
+                ctx.logger.warn(
+                    `[notify] no messaging service registered; notification "${title}" not delivered`,
+                );
+                return {
+                    success: true,
+                    output: { delivered: 0, failed: 0, skipped: true },
+                };
+            }
+
+            try {
+                const result = await messaging.emit({
+                    topic,
+                    title,
+                    body,
+                    severity,
+                    recipients,
+                    channels: channels.length ? channels : undefined,
+                    actionUrl,
+                    payload,
+                });
+                return {
+                    success: true,
+                    output: { delivered: result.delivered, failed: result.failed },
+                };
+            } catch (err) {
+                return { success: false, error: `notify failed: ${(err as Error).message}` };
+            }
+        },
+    });
+
+    ctx.logger.info('[Notify] 1 built-in node executor registered (notify)');
+}