Merge branch 'main' of https://github.com/objectstack-ai/framework

Author: os-zhuang

.changeset/config.json

@@ -37,6 +37,9 @@
       "@objectstack/plugin-security",
       "@objectstack/plugin-sharing",
       "@objectstack/plugin-webhooks",
+      "@objectstack/plugin-trigger-record-change",
+      "@objectstack/connector-rest",
+      "@objectstack/connector-slack",
       "@objectstack/express",
       "@objectstack/fastify",
       "@objectstack/hono",
@@ -55,6 +58,7 @@
       "@objectstack/service-i18n",
       "@objectstack/service-job",
       "@objectstack/service-knowledge",
+      "@objectstack/service-messaging",
       "@objectstack/service-package",
       "@objectstack/service-queue",
       "@objectstack/service-realtime",

.changeset/record-change-flow-trigger.md

@@ -0,0 +1,42 @@
+---
+"@objectstack/plugin-trigger-record-change": minor
+"@objectstack/service-automation": minor
+"@objectstack/spec": patch
+---
+
+Record-change flow trigger — auto-launch flows on data mutations.
+
+Completes the automation engine's `FlowTrigger` extension point so flows whose
+`start` node declares a record-change trigger (`config: { objectName,
+triggerType: 'record-after-update', condition }`) actually fire on the matching
+mutation. Previously the slot was dead — nothing called `trigger.start` — so
+such flows could only run via a manual `engine.execute()`.
+
+**Engine baseline (`@objectstack/service-automation`)**
+- Redefines `FlowTrigger` around a parsed `FlowTriggerBinding` (flowName,
+  object, event, condition, schedule, raw config). The engine parses the start
+  node and hands the trigger a normalized binding, keeping trigger plugins
+  decoupled from flow-definition internals (mirrors `connector_action` ↔
+  `connector-rest`).
+- Ordering-independent, bidirectional wiring: `registerFlow`/`toggleFlow`
+  activate bindings; `registerTrigger` retro-binds already-registered flows (a
+  trigger plugin wires up on `kernel:ready`, after flows are pulled in);
+  `unregisterFlow`/`unregisterTrigger`/disable tear them down.
+- Centralized start-condition gate in `execute()`: the start node's `condition`
+  (e.g. `status == 'done' && previous.status != 'done'`) is evaluated once for
+  every trigger type and manual runs; false ⇒ `{ skipped: true }`.
+- Seeds `record`, flattened record fields, and `previous` into flow variables.
+- New `getActiveTriggerBindings()` getter + exports `FlowTriggerBinding`.
+
+**Spec (`@objectstack/spec`)**
+- Adds `previous?` to `AutomationContext` — the pre-update "old" row, so flows
+  can gate on transitions.
+
+**New package (`@objectstack/plugin-trigger-record-change`)**
+- The concrete trigger: subscribes to ObjectQL lifecycle hooks
+  (`record-after-update` → `afterUpdate`, etc.), builds an `AutomationContext`
+  from the new/old record, and runs the flow. Error-isolated (a flow failure
+  never breaks the CRUD write); graceful degrade when the automation service or
+  ObjectQL engine is absent (mirrors `plugin-audit`).
+
+The `schedule` trigger (ticker/cron + `sys_job` lifecycle) is a follow-up.

packages/plugins/plugin-trigger-record-change/README.md

@@ -0,0 +1,63 @@
+# @objectstack/plugin-trigger-record-change
+
+Auto-launch ObjectStack flows on record changes.
+
+The automation engine ships the `FlowTrigger` extension point and the wiring
+that turns a flow's `start` node into a normalized trigger binding — but the
+*concrete* record-change trigger lives here, as a plugin. This mirrors the
+connector split (engine baseline + `connector-rest` plugin) and reuses the same
+`kernel:ready` → `getService('objectql')` pattern `plugin-audit` uses to reach
+the data engine's lifecycle-hook surface.
+
+## What it does
+
+A flow whose `start` node declares a record-change trigger:
+
+```ts
+{
+  type: 'start',
+  config: {
+    objectName: 'showcase_task',
+    triggerType: 'record-after-update',
+    condition: "status == 'done' && previous.status != 'done'", // optional
+  },
+}
+```
+
+auto-launches whenever a matching mutation happens — no manual
+`engine.execute()`. The engine evaluates the optional `condition` (the start
+node gate) before running the flow, with `record` (the new row) and `previous`
+(the old row) in scope.
+
+### Trigger event → hook mapping
+
+| `triggerType`            | ObjectQL hook  |
+| ------------------------ | -------------- |
+| `record-after-create`    | `afterInsert`  |
+| `record-after-update`    | `afterUpdate`  |
+| `record-after-delete`    | `afterDelete`  |
+| `record-before-create`   | `beforeInsert` |
+| `record-before-update`   | `beforeUpdate` |
+| `record-before-delete`   | `beforeDelete` |
+
+## Usage
+
+```ts
+import { AutomationServicePlugin } from '@objectstack/service-automation';
+import { MessagingServicePlugin } from '@objectstack/service-messaging';
+import { RecordChangeTriggerPlugin } from '@objectstack/plugin-trigger-record-change';
+
+kernel
+  .use(new AutomationServicePlugin())   // engine + flows
+  .use(new MessagingServicePlugin())    // notify channels (optional)
+  .use(new RecordChangeTriggerPlugin()); // ← makes record-change flows live
+```
+
+Requires the ObjectQL engine (`com.objectstack.engine.objectql`). If either the
+automation service or the data engine is unavailable at `kernel:ready`, the
+plugin logs a warning and no-ops rather than failing startup.
+
+## Error isolation
+
+A flow that throws during a triggered run is logged and swallowed — it never
+breaks the CRUD write that triggered it.

packages/plugins/plugin-trigger-record-change/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@objectstack/plugin-trigger-record-change",
+  "version": "7.3.0",
+  "license": "Apache-2.0",
+  "description": "Record-change flow trigger for ObjectStack — auto-launches flows on object insert/update/delete via ObjectQL lifecycle hooks (ADR-0018)",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup --config ../../../tsup.config.ts",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@objectstack/core": "workspace:*",
+    "@objectstack/spec": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "keywords": [
+    "objectstack",
+    "plugin",
+    "automation",
+    "flow",
+    "trigger",
+    "record-change"
+  ],
+  "author": "ObjectStack",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/objectstack-ai/framework.git",
+    "directory": "packages/plugins/plugin-trigger-record-change"
+  },
+  "homepage": "https://objectstack.ai/docs",
+  "bugs": "https://github.com/objectstack-ai/framework/issues",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

packages/plugins/plugin-trigger-record-change/src/index.ts

@@ -0,0 +1,13 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+export { RecordChangeTriggerPlugin } from './plugin.js';
+export {
+    RecordChangeTrigger,
+    triggerTypeToHookEvent,
+} from './record-change-trigger.js';
+export type {
+    FlowTrigger,
+    FlowTriggerBinding,
+    RecordChangeDataEngine,
+    TriggerLogger,
+} from './record-change-trigger.js';

packages/plugins/plugin-trigger-record-change/src/plugin.ts

@@ -0,0 +1,85 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { Plugin, PluginContext } from '@objectstack/core';
+import { RecordChangeTrigger } from './record-change-trigger.js';
+import type { FlowTrigger, RecordChangeDataEngine } from './record-change-trigger.js';
+
+/**
+ * The slice of the automation engine this plugin needs: register a trigger on
+ * its `FlowTrigger` extension point. Declared structurally so the plugin does
+ * not take a build dependency on `@objectstack/service-automation`.
+ */
+interface AutomationTriggerRegistry {
+    registerTrigger(trigger: FlowTrigger): void;
+    unregisterTrigger?(type: string): void;
+}
+
+/**
+ * RecordChangeTriggerPlugin
+ *
+ * Makes record-change-triggered flows actually fire. The automation engine
+ * ships the `FlowTrigger` wiring (it parses each flow's start node into a
+ * binding and calls `trigger.start(...)`), but the *concrete* record-change
+ * trigger — the one that subscribes to ObjectQL lifecycle hooks — lives here as
+ * a plugin. This mirrors the connector split (engine baseline + connector-rest
+ * plugin) and reuses plugin-audit's `kernel:ready` → `getService('objectql')`
+ * pattern to reach the data engine's hook surface.
+ *
+ * With this plugin installed, a flow whose start node declares
+ * `config: { objectName, triggerType: 'record-after-update', condition }`
+ * auto-launches on the matching mutation — no manual `engine.execute()`.
+ */
+export class RecordChangeTriggerPlugin implements Plugin {
+    name = 'com.objectstack.trigger.record-change';
+    type = 'standard';
+    version = '7.3.0';
+    dependencies = ['com.objectstack.engine.objectql'];
+
+    async init(ctx: PluginContext): Promise<void> {
+        ctx.logger.info('Record-change trigger plugin initialized');
+    }
+
+    async start(ctx: PluginContext): Promise<void> {
+        // ObjectQL engine + the automation service are only resolvable once the
+        // kernel is ready (kernel:ready fires after AutomationServicePlugin.start()
+        // has pulled flows into the engine, so binding order is correct).
+        ctx.hook('kernel:ready', async () => {
+            const automation = this.resolveService<AutomationTriggerRegistry>(ctx, 'automation');
+            if (!automation || typeof automation.registerTrigger !== 'function') {
+                ctx.logger.warn(
+                    'RecordChangeTriggerPlugin: automation service not available — record-change trigger NOT installed',
+                );
+                return;
+            }
+
+            const engine = this.resolveDataEngine(ctx);
+            if (!engine || typeof engine.registerHook !== 'function') {
+                ctx.logger.warn(
+                    'RecordChangeTriggerPlugin: ObjectQL engine not available — record-change trigger NOT installed',
+                );
+                return;
+            }
+
+            const trigger = new RecordChangeTrigger(engine, ctx.logger);
+            automation.registerTrigger(trigger);
+            ctx.logger.info('RecordChangeTriggerPlugin: record-change trigger registered');
+        });
+    }
+
+    private resolveService<T>(ctx: PluginContext, name: string): T | null {
+        try {
+            return ctx.getService<T>(name) ?? null;
+        } catch {
+            return null;
+        }
+    }
+
+    private resolveDataEngine(ctx: PluginContext): RecordChangeDataEngine | null {
+        // Primary alias 'objectql', fallback 'data' (some kernels register the
+        // engine under both) — same lookup plugin-audit uses.
+        return (
+            this.resolveService<RecordChangeDataEngine>(ctx, 'objectql') ??
+            this.resolveService<RecordChangeDataEngine>(ctx, 'data')
+        );
+    }
+}