refactor(service-automation): take the trigger kind from spec's shared resolver

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**

.changeset/engine-trigger-kind-from-spec-resolver.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-automation": patch
+---
+
+refactor(service-automation): take the trigger KIND from spec's `resolveFlowTriggerKind` instead of a second private copy of the chain (#14328)
+
+No behaviour change and no API change — `patch` because nothing observable moves.
+`resolveTriggerBinding` is `private`, no export is added or removed, no payload
+key changes, and the kind reported for every flow is the kind reported before
+(1,223 `service-automation` cases and 81 `trigger-record-change` cases green
+unchanged, plus new pins across the whole precedence chain). What changes is that
+one rule now has one home.
+
+**The defect.** `AutomationEngine.resolveTriggerBinding` hand-kept the chain that
+decides which trigger a flow asks for — string `record-*` token, array form,
+`timeRelative` descriptor, `schedule` cadence or `type: 'schedule'`, `type: 'api'`
+or `triggerType: 'api'` — in parallel with `@objectstack/spec`'s
+`resolveFlowTriggerKind`, the authoring-time mirror of that same rule. Both
+authoring surfaces already read the spec one: `defineStack`'s trigger-capability
+refusal and `@objectstack/lint`'s `validate-flow-trigger-readiness`. The engine
+did not, and nothing pinned the two together. A branch added to one side leaves
+`defineStack` accepting a stack the runtime leaves inert, or refusing one it would
+arm — the drift the shared resolver was hoisted to prevent, reopened one layer
+down. The two agreed on every string-form flow, so this was an observation rather
+than a live defect; the harm was future drift.
+
+**The shape.** `resolveTriggerBinding` now takes its kind from
+`resolveFlowTriggerKind(flow)` and keeps only the per-kind BINDING construction —
+which start-node fields each trigger needs. `getTriggerBindingAudit` and the boot
+banner therefore name the kind authoring named, by construction.
+
+**The one deliberate divergence is preserved, not unified.** The ARRAY form of
+`triggerType` (`['record-after-create', 'record-after-delete']`) resolves to *no*
+kind in spec — multi-event unions are unsupported (#3457), and reading the shape
+as "asks for a record-change trigger" would have `defineStack` demand a capability
+the flow can never use and would widen the lint rule's auto-triggered set. The
+engine routes it to the record-change trigger anyway, from an explicit pre-check
+that runs BEFORE the resolver, for one reason: so that trigger refuses it LOUDLY
+at bind time (#3481) instead of the flow folding into "manual" and vanishing from
+every surface. Pre-check *ordering* is load-bearing too — array form outranks
+`timeRelative`, which the resolver, blind to the array, would otherwise answer for
+a start node carrying both.
+
+**What now catches the drift.** Two guards, one static and one runtime. The
+per-kind `switch` is exhaustive over `FlowTriggerKind` with a `never` default, so a
+kind added to spec fails this package's type-check until its binding shape is
+written; and a new case asserts every kind in `FLOW_TRIGGER_KINDS` is reachable
+through the real engine. The preserved divergence is pinned on both sides: engine
+routing and pre-check precedence in `service-automation`, and the refusal itself —
+asserted as a refusal, on a binding the real engine produced — end-to-end against
+the real trigger in `@objectstack/trigger-record-change`.

packages/services/service-automation/src/engine.ts

@@ -20,6 +20,11 @@ import {
 } from './screen-input-contract.js';
 import type { Logger } from '@objectstack/spec/contracts';
 import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlowGraphs, findRegionEntry, defineActionDescriptor } from '@objectstack/spec/automation';
+// [#14328] The ONE answer to "which trigger kind does this flow ask for?" —
+// shared with `defineStack`'s trigger-capability refusal and `@objectstack/lint`'s
+// `validate-flow-trigger-readiness`, so the runtime cannot drift from what
+// authoring accepted. See `resolveTriggerBinding`.
+import { resolveFlowTriggerKind } from '@objectstack/spec/automation';
 import { resolveFlowNodeExpressions } from '@objectstack/spec/automation';
 import { applyConversionsToFlow, type ConversionNotice, type ConversionConflictNotice } from '@objectstack/spec';
 // [ADR-0126 §7.3] "Does a code package ship this flow?" for the subflow guard.
@@ -2448,6 +2453,17 @@ export class AutomationEngine implements IAutomationService {
  * established by the showcase flows — is that the start node carries the
  * trigger details in its `config`: `{ objectName, triggerType, condition }`
  * for record-change, or a `schedule` descriptor for time-based flows.
+ *
+ * [#14328] WHICH KIND a flow asks for is not decided here: it is
+ * {@link resolveFlowTriggerKind}'s answer, the one `@objectstack/spec`
+ * export that `defineStack`'s trigger-capability refusal and
+ * `@objectstack/lint`'s `validate-flow-trigger-readiness` already read.
+ * This method keeps only the per-kind BINDING construction — which start-node
+ * fields each trigger needs. Before #14328 the chain was hand-kept here in
+ * parallel with the spec one, and nothing pinned them together: a branch
+ * added on one side left `defineStack` accepting a stack the runtime leaves
+ * inert, or refusing one it would arm. Now `getTriggerBindingAudit` and the
+ * boot banner name the kind authoring named, by construction.
  */
  private resolveTriggerBinding(
  flowName: string,
@@ -2456,20 +2472,7 @@ export class AutomationEngine implements IAutomationService {
  if (!flow) return undefined;
  const startNode = flow.nodes.find(n => n.type === 'start');
  const config = (startNode?.config ?? {}) as Record<string, unknown>;
- const triggerType = typeof config.triggerType === 'string' ? config.triggerType : undefined;
-
- if (triggerType && triggerType.startsWith('record-')) {
- return {
- triggerType: 'record_change',
- binding: {
- flowName,
- object: typeof config.objectName === 'string' ? config.objectName : undefined,
- event: triggerType,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const condition = (config.condition as FlowTriggerBinding['condition']) ?? undefined;
 
  // Array-form triggerType (e.g. ['record-after-create', 'record-after-delete']).
  // Multi-event unions are deliberately unsupported (#3457). But a non-string
@@ -2483,6 +2486,18 @@ export class AutomationEngine implements IAutomationService {
  // raw array is preserved in `config` so the trigger can tailor its message;
  // `event` is a joined string so the trigger's single-token mapper reports it
  // verbatim and maps it to no hook.
+ //
+ // [#14328] This stays an explicit pre-check BEFORE `resolveFlowTriggerKind`,
+ // and that is the ONE deliberate divergence between the two — documented in
+ // that resolver's own header. It resolves array form to NO kind on purpose:
+ // reading it as "asks for a record-change trigger" would have `defineStack`
+ // demand a capability for a flow that can never use it and would widen the
+ // lint rule's auto-triggered set. The route below is a DIAGNOSTIC route, not
+ // a trigger the flow could fire on; folding it into the shared resolver would
+ // delete a standing decision and turn a loud refusal into silence. Pre-check
+ // ordering also preserves this method's own precedence exactly: array form
+ // outranks `timeRelative`/`schedule`, which the resolver — blind to it —
+ // would otherwise answer for a start node carrying both.
  if (
  Array.isArray(config.triggerType) &&
  config.triggerType.some((t) => typeof t === 'string' && (t as string).startsWith('record-'))
@@ -2493,56 +2508,86 @@ export class AutomationEngine implements IAutomationService {
  flowName,
  object: typeof config.objectName === 'string' ? config.objectName : undefined,
  event: config.triggerType.filter((t) => typeof t === 'string').join(','),
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
+ condition,
  config,
  },
  };
  }
 
- // Declarative time-relative sweep (#1874): a start node carrying a
- // `timeRelative` descriptor is swept on a schedule and launched once per
- // record whose date field falls in the window. Checked BEFORE `schedule`
- // because such a flow ALSO carries a `schedule` cadence (the sweep
- // interval) — without this precedence it would bind to the plain schedule
- // trigger and fire once with no record instead of once per record.
- if (config.timeRelative != null && typeof config.timeRelative === 'object') {
- const tr = config.timeRelative as Record<string, unknown>;
- return {
- triggerType: 'time_relative',
- binding: {
- flowName,
- object:
- typeof tr.object === 'string'
- ? tr.object
- : typeof config.objectName === 'string'
- ? config.objectName
- : undefined,
- schedule: config.schedule,
- condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined,
- config,
- },
- };
- }
+ const kind = resolveFlowTriggerKind(flow);
+ if (!kind) return undefined;
 
- if (config.schedule != null || flow.type === 'schedule') {
- return {
- triggerType: 'schedule',
- binding: { flowName, schedule: config.schedule, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ switch (kind) {
+ case 'record_change':
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object: typeof config.objectName === 'string' ? config.objectName : undefined,
+ // A `record-*` kind means `config.triggerType` IS that string
+ // token — the resolver read it to answer; the narrowing is
+ // re-stated because the answer does not carry it back.
+ event: typeof config.triggerType === 'string' ? config.triggerType : undefined,
+ condition,
+ config,
+ },
+ };
 
- // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
- // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
- // endpoint and enqueues; the binding's `config` carries the hook
- // details (`hookId`, `secret`) from the start node.
- if (flow.type === 'api' || triggerType === 'api') {
- return {
- triggerType: 'api',
- binding: { flowName, condition: (config.condition as FlowTriggerBinding['condition']) ?? undefined, config },
- };
- }
+ // Declarative time-relative sweep (#1874): a start node carrying a
+ // `timeRelative` descriptor is swept on a schedule and launched once per
+ // record whose date field falls in the window. The resolver ranks it
+ // BEFORE `schedule` for the same reason this method did — such a flow
+ // ALSO carries a `schedule` cadence (the sweep interval), and without
+ // that precedence it would bind to the plain schedule trigger and fire
+ // once with no record instead of once per record.
+ case 'time_relative': {
+ const tr = (config.timeRelative ?? {}) as Record<string, unknown>;
+ return {
+ triggerType: kind,
+ binding: {
+ flowName,
+ object:
+ typeof tr.object === 'string'
+ ? tr.object
+ : typeof config.objectName === 'string'
+ ? config.objectName
+ : undefined,
+ schedule: config.schedule,
+ condition,
+ config,
+ },
+ };
+ }
+
+ case 'schedule':
+ return {
+ triggerType: kind,
+ binding: { flowName, schedule: config.schedule, condition, config },
+ };
+
+ // Inbound HTTP (ADR-0041 Tier 1): an `api` flow waits for an external
+ // POST. The concrete trigger (`@objectstack/trigger-api`) mounts the
+ // endpoint and enqueues; the binding's `config` carries the hook
+ // details (`hookId`, `secret`) from the start node.
+ case 'api':
+ return {
+ triggerType: kind,
+ binding: { flowName, condition, config },
+ };
 
- return undefined;
+ default: {
+ // [#14328] Exhaustive over `FlowTriggerKind`, and that is the point:
+ // a kind added to the spec resolver makes `kind` no longer `never`
+ // here, so THIS package's type-check fails until the binding shape
+ // for it is written — the drift is caught at the commit that opens
+ // it instead of showing up as a flow that arms nowhere. At run time
+ // (a spec build ahead of this one) fall back to today's behaviour —
+ // no binding — rather than throwing inside the boot audit.
+ const unhandledKind: never = kind;
+ void unhandledKind;
+ return undefined;
+ }
+ }
  }
 
  /**