@teleporthq/teleport-plugin-next-workflows 0.43.29 → 0.43.31

package/__tests__/_helpers/load-handler.ts

@@ -16,7 +16,17 @@ import { nodeRegistry } from '../../src'
 //
 // (The polyfills are the verbatim TS 4.x emit, kept in sync with the
 // upstream `__awaiter` / `__generator` definitions tslib ships.)
-const TS_EMIT_HELPERS = `var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+const TS_EMIT_HELPERS = `var __assign = (this && this.__assign) || function () {
+  __assign = Object.assign || function(t) {
+    for (var s, i = 1, n = arguments.length; i < n; i++) {
+      s = arguments[i];
+      for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p)) t[p] = s[p];
+    }
+    return t;
+  };
+  return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
   function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
   return new (P || (P = Promise))(function (resolve, reject) {
     function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }

package/__tests__/file-storage-upload-picked-files.test.ts

@@ -0,0 +1,135 @@
+// Pins the file-storage-upload contract the tq-form-file-input primitive
+// relies on: the form-submit workflow does state-get-local-state(<state>) ->
+// file-storage-upload(file = <PickedFile[]>), so the handler must accept an
+// ARRAY of `{ name, size, type, lastModified, dataURL }` POJOs (the exact
+// shape browser-pick-files emits) and convert every dataURL to a Blob before
+// POSTing the FormData.
+
+import { Blob as NodeBlob } from 'buffer'
+import { loadHandler, HandlerFn } from './_helpers/load-handler'
+
+// jest 26's node sandbox exposes none of the browser upload globals the
+// handler uses (FormData/Blob/atob/fetch), so the test installs minimal
+// stand-ins: Node's own Blob, a Buffer-backed atob, and a FormData stub
+// that records appends the way the assertions need them.
+class FormDataStub {
+  public appended: Array<{ key: string; value: unknown; fileName?: string }> = []
+
+  public append(key: string, value: unknown, fileName?: string): void {
+    this.appended.push({ key, value, fileName })
+  }
+
+  public getAll(key: string): Array<{ value: unknown; fileName?: string }> {
+    return this.appended
+      .filter((entry) => entry.key === key)
+      .map((entry) => ({ value: entry.value, fileName: entry.fileName }))
+  }
+}
+
+const toDataURL = (mime: string, content: string): string =>
+  `data:${mime};base64,${Buffer.from(content).toString('base64')}`
+
+const blobText = async (value: unknown): Promise<string> =>
+  Buffer.from(await (value as InstanceType<typeof NodeBlob>).arrayBuffer()).toString()
+
+describe('file-storage-upload: PickedFile array from state', () => {
+  let fetchMock: jest.Mock
+  let handler: HandlerFn
+
+  beforeEach(() => {
+    handler = loadHandler('file-storage-upload')
+    fetchMock = jest.fn(async () => ({
+      ok: true,
+      json: async () => ({
+        files: [
+          { id: '1', name: 'a.png', url: 'https://storage.example/a.png' },
+          { id: '2', name: 'b.txt', url: 'https://storage.example/b.txt' },
+        ],
+      }),
+    }))
+    ;(globalThis as any).fetch = fetchMock
+    ;(globalThis as any).FormData = FormDataStub
+    ;(globalThis as any).Blob = NodeBlob
+    ;(globalThis as any).atob = (encoded: string) =>
+      Buffer.from(encoded, 'base64').toString('binary')
+  })
+
+  afterEach(() => {
+    delete (globalThis as any).fetch
+    delete (globalThis as any).FormData
+    delete (globalThis as any).Blob
+    delete (globalThis as any).atob
+  })
+
+  it('converts every PickedFile dataURL to a Blob and appends all of them', async () => {
+    const pickedFiles = [
+      {
+        name: 'a.png',
+        size: 9,
+        type: 'image/png',
+        lastModified: 1,
+        dataURL: toDataURL('image/png', 'png-bytes'),
+      },
+      {
+        name: 'b.txt',
+        size: 9,
+        type: 'text/plain',
+        lastModified: 2,
+        dataURL: toDataURL('text/plain', 'txt-bytes'),
+      },
+    ]
+
+    const result = (await handler({ file: pickedFiles }, {})) as { files: Array<{ url: string }> }
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('/api/runtime-storage/upload')
+    const entries = (init.body as FormDataStub).getAll('file')
+    expect(entries).toHaveLength(2)
+    expect(entries[0].fileName).toBe('a.png')
+    expect((entries[0].value as InstanceType<typeof NodeBlob>).type).toBe('image/png')
+    expect(await blobText(entries[0].value)).toBe('png-bytes')
+    expect(entries[1].fileName).toBe('b.txt')
+    expect((entries[1].value as InstanceType<typeof NodeBlob>).type).toBe('text/plain')
+    expect(await blobText(entries[1].value)).toBe('txt-bytes')
+
+    expect(result.files.map((f) => f.url)).toEqual([
+      'https://storage.example/a.png',
+      'https://storage.example/b.txt',
+    ])
+  })
+
+  it('skips array entries without a usable dataURL but uploads the rest', async () => {
+    const pickedFiles = [
+      { name: 'broken.png', size: 1, type: 'image/png', lastModified: 1 },
+      {
+        name: 'ok.png',
+        size: 9,
+        type: 'image/png',
+        lastModified: 2,
+        dataURL: toDataURL('image/png', 'ok-bytes'),
+      },
+    ]
+
+    await handler({ file: pickedFiles }, {})
+
+    const entries = (fetchMock.mock.calls[0][1].body as FormDataStub).getAll('file')
+    expect(entries).toHaveLength(1)
+    expect(entries[0].fileName).toBe('ok.png')
+  })
+
+  it('returns an error without fetching when no array entry is convertible', async () => {
+    const result = await handler({ file: [{ name: 'x.png', type: 'image/png' }] }, {})
+
+    expect(result).toEqual({ files: [], error: 'Invalid file data' })
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('never throws for an empty selection — the submit chain needs no if-gate', async () => {
+    // An untouched form-file-input state is [] and reaches the node as-is.
+    const result = await handler({ file: [] }, {})
+
+    expect(result).toEqual({ files: [], error: 'Invalid file data' })
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+})

package/__tests__/graph-utils-topological-order.test.ts

@@ -0,0 +1,108 @@
+import { getTopologicalOrder, collectWorkflowContextNodeIds } from '../src/graph-utils'
+import type { UIDLWorkflowNode, UIDLWorkflowEdge } from '@teleporthq/teleport-types'
+
+const node = (
+  id: string,
+  type: string,
+  stepNumber: number,
+  config: Record<string, unknown> = {}
+): UIDLWorkflowNode => ({
+  id,
+  type,
+  label: id,
+  config,
+  executionEnv: type === 'data-create-item' || type.startsWith('data-') ? 'server' : 'client',
+  stepNumber,
+})
+
+const wfCtx = (nodeId: string) => ({
+  type: 'workflowContext',
+  nodeId,
+  path: [nodeId, 'value'],
+})
+
+describe('collectWorkflowContextNodeIds', () => {
+  it('finds workflowContext node ids nested in arrays and objects', () => {
+    const config = {
+      columnMappings: [
+        { column: 'title', value: wfCtx('get-title') },
+        { column: 'type_field', value: wfCtx('get-type') },
+      ],
+      filters: [{ field: 'id', value: '{{Current Page Entity.id}}' }],
+    }
+    const out = new Set<string>()
+    collectWorkflowContextNodeIds(config, out)
+    expect(Array.from(out).sort()).toEqual(['get-title', 'get-type'])
+  })
+})
+
+describe('getTopologicalOrder — implicit workflowContext dependencies', () => {
+  it('orders a state-get BEFORE the data-create that reads it via columnMappings (no explicit edge)', () => {
+    // Reproduces run 0a5f554e: the create references get-state-type only through
+    // its config; there is NO explicit edge between them.
+    const nodes = [
+      node('trig', 'event-form-submitted', 0),
+      node('insert-title', 'data-create-item', 0, {
+        tableName: 'titles',
+        columnMappings: [{ column: 'type_field', value: wfCtx('get-state-type') }],
+      }),
+      node('get-state-type', 'state-get-local-state', 3, { property: 'typeField' }),
+    ]
+    const edges: UIDLWorkflowEdge[] = [{ id: 'e1', source: 'trig', target: 'get-state-type' }]
+
+    const order = getTopologicalOrder(nodes, edges)
+    expect(order.indexOf('get-state-type')).toBeLessThan(order.indexOf('insert-title'))
+  })
+
+  it('does not reorder a correctly wired linear workflow', () => {
+    const nodes = [
+      node('trig', 'event-element-clicked', 0),
+      node('get', 'state-get-local-state', 1, { property: 'q' }),
+      node('sel', 'data-select', 2, {
+        tableName: 't',
+        filters: [{ field: 'q', value: wfCtx('get') }],
+      }),
+      node('upd', 'state-update-local-state', 3, { property: 'rows' }),
+    ]
+    const edges: UIDLWorkflowEdge[] = [
+      { id: 'e1', source: 'trig', target: 'get' },
+      { id: 'e2', source: 'get', target: 'sel' },
+      { id: 'e3', source: 'sel', target: 'upd' },
+    ]
+    expect(getTopologicalOrder(nodes, edges)).toEqual(['trig', 'get', 'sel', 'upd'])
+  })
+
+  it('ignores a workflowContext ref to a control-flow (loop) node', () => {
+    // A node reading a loop's currentItem must NOT be forced after the loop via a
+    // synthetic data edge (loop bodies are handled by dedicated edge handles).
+    const nodes = [
+      node('trig', 'event-element-clicked', 0),
+      node('reader', 'data-create-item', 1, {
+        tableName: 't',
+        columnMappings: [
+          {
+            column: 'x',
+            value: { type: 'workflowContext', nodeId: 'loop', path: ['loop', 'currentItem'] },
+          },
+        ],
+      }),
+      node('loop', 'general-loop', 5, {}),
+    ]
+    const edges: UIDLWorkflowEdge[] = [{ id: 'e1', source: 'trig', target: 'reader' }]
+    // No virtual edge loop->reader is added, so reader (step 1) stays before loop (step 5).
+    const order = getTopologicalOrder(nodes, edges)
+    expect(order.indexOf('reader')).toBeLessThan(order.indexOf('loop'))
+  })
+
+  it('tolerates self / unknown refs without crashing', () => {
+    const nodes = [
+      node('trig', 'event-element-clicked', 0),
+      node('a', 'data-select', 1, {
+        filters: [{ value: wfCtx('a') }, { value: wfCtx('ghost') }],
+      }),
+    ]
+    const edges: UIDLWorkflowEdge[] = [{ id: 'e1', source: 'trig', target: 'a' }]
+    expect(() => getTopologicalOrder(nodes, edges)).not.toThrow()
+    expect(getTopologicalOrder(nodes, edges)).toEqual(['trig', 'a'])
+  })
+})

package/__tests__/runtime-operator-aliases.test.ts

@@ -0,0 +1,180 @@
+import { generateSharedRuntimeUtilsCode } from '../src'
+
+// Regression guard for the operator-vocabulary mismatch (FurniFlow run
+// be21af83): the worker canonicalizes if-statement operators to snake_case
+// (is_not_empty, greater_than) and the GUI emits camelCase named forms
+// (startsWith, notContains), but the generated runtime only implemented the
+// hyphenated spellings. Unknown operators fell through to `left == right`,
+// INVERTING unary semantics — a correctly filled stock-movement form
+// evaluated is_not_empty(value) as `value == undefined` → false → the
+// submit silently no-oped and success/error toasts were swapped.
+
+type SharedUtils = {
+  evaluateSingleComparison: (cfg: unknown, ctx: Record<string, unknown>) => boolean
+  evaluateCondition: (cfg: unknown, ctx: Record<string, unknown>) => boolean
+  normalizeComparisonOperator: (op: unknown) => string
+}
+
+function loadSharedRuntime(): SharedUtils {
+  const src = generateSharedRuntimeUtilsCode()
+  const wrapper: { exports: Record<string, unknown> } = { exports: {} }
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval
+  new Function('module', 'exports', src)(wrapper, wrapper.exports)
+  return wrapper.exports as unknown as SharedUtils
+}
+
+describe('workflow runtime operator aliases', () => {
+  const utils = loadSharedRuntime()
+
+  it('normalizes snake_case, camelCase and named operators to the canonical form', () => {
+    expect(utils.normalizeComparisonOperator('is_not_empty')).toBe('is-not-empty')
+    expect(utils.normalizeComparisonOperator('is_empty')).toBe('is-empty')
+    expect(utils.normalizeComparisonOperator('not_equals')).toBe('not-equals')
+    expect(utils.normalizeComparisonOperator('greater_than')).toBe('greater-than')
+    expect(utils.normalizeComparisonOperator('less_than')).toBe('less-than')
+    expect(utils.normalizeComparisonOperator('greater_than_or_equal')).toBe('greater-than-or-equal')
+    expect(utils.normalizeComparisonOperator('less_than_or_equal')).toBe('less-than-or-equal')
+    expect(utils.normalizeComparisonOperator('starts_with')).toBe('starts-with')
+    expect(utils.normalizeComparisonOperator('startsWith')).toBe('starts-with')
+    expect(utils.normalizeComparisonOperator('ends_with')).toBe('ends-with')
+    expect(utils.normalizeComparisonOperator('endsWith')).toBe('ends-with')
+    expect(utils.normalizeComparisonOperator('not_contains')).toBe('not-contains')
+    expect(utils.normalizeComparisonOperator('notContains')).toBe('not-contains')
+    expect(utils.normalizeComparisonOperator('equals')).toBe('equals')
+    expect(utils.normalizeComparisonOperator('matchesRegex')).toBe('matches-regex')
+    // symbol operators pass through untouched
+    expect(utils.normalizeComparisonOperator('===')).toBe('===')
+    expect(utils.normalizeComparisonOperator('!=')).toBe('!=')
+    expect(utils.normalizeComparisonOperator('>')).toBe('>')
+  })
+
+  it('evaluates is_not_empty as a UNARY check (previously inverted)', () => {
+    // filled value → true (used to be `value == undefined` → false)
+    expect(
+      utils.evaluateSingleComparison({ leftValue: 'receipt', operator: 'is_not_empty' }, {})
+    ).toBe(true)
+    // empty value → false (used to be true)
+    expect(utils.evaluateSingleComparison({ leftValue: '', operator: 'is_not_empty' }, {})).toBe(
+      false
+    )
+    expect(
+      utils.evaluateSingleComparison({ leftValue: undefined, operator: 'is_not_empty' }, {})
+    ).toBe(false)
+    expect(utils.evaluateSingleComparison({ leftValue: [], operator: 'is_not_empty' }, {})).toBe(
+      false
+    )
+  })
+
+  it('evaluates is_empty / is_null / is_not_null / is_true / is_false', () => {
+    expect(utils.evaluateSingleComparison({ leftValue: '', operator: 'is_empty' }, {})).toBe(true)
+    expect(utils.evaluateSingleComparison({ leftValue: 'x', operator: 'is_empty' }, {})).toBe(false)
+    expect(utils.evaluateSingleComparison({ leftValue: null, operator: 'is_null' }, {})).toBe(true)
+    expect(utils.evaluateSingleComparison({ leftValue: '', operator: 'is_null' }, {})).toBe(false)
+    expect(utils.evaluateSingleComparison({ leftValue: 0, operator: 'is_not_null' }, {})).toBe(true)
+    expect(utils.evaluateSingleComparison({ leftValue: 'true', operator: 'is_true' }, {})).toBe(
+      true
+    )
+    expect(utils.evaluateSingleComparison({ leftValue: false, operator: 'is_false' }, {})).toBe(
+      true
+    )
+  })
+
+  it('evaluates named binary operators', () => {
+    expect(
+      utils.evaluateSingleComparison(
+        { leftValue: 5, rightValue: '3', operator: 'greater_than' },
+        {}
+      )
+    ).toBe(true)
+    expect(
+      utils.evaluateSingleComparison({ leftValue: 2, rightValue: '3', operator: 'less_than' }, {})
+    ).toBe(true)
+    expect(
+      utils.evaluateSingleComparison(
+        { leftValue: 3, rightValue: '3', operator: 'greater_than_or_equal' },
+        {}
+      )
+    ).toBe(true)
+    expect(
+      utils.evaluateSingleComparison(
+        { leftValue: 3, rightValue: '3', operator: 'less_than_or_equal' },
+        {}
+      )
+    ).toBe(true)
+    expect(
+      utils.evaluateSingleComparison(
+        { leftValue: 'a', rightValue: 'b', operator: 'not_equals' },
+        {}
+      )
+    ).toBe(true)
+    expect(
+      utils.evaluateSingleComparison(
+        { leftValue: 'receipt-1', rightValue: 'receipt', operator: 'startsWith' },
+        {}
+      )
+    ).toBe(true)
+    expect(
+      utils.evaluateSingleComparison(
+        { leftValue: 'receipt-1', rightValue: '-1', operator: 'ends_with' },
+        {}
+      )
+    ).toBe(true)
+    expect(
+      utils.evaluateSingleComparison(
+        { leftValue: 'abc', rightValue: 'z', operator: 'notContains' },
+        {}
+      )
+    ).toBe(true)
+  })
+
+  it('warns on a genuinely unknown operator instead of silently comparing', () => {
+    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => undefined)
+    utils.evaluateSingleComparison({ leftValue: 1, rightValue: 1, operator: 'sorta-equalish' }, {})
+    expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('sorta-equalish'))
+    warnSpy.mockRestore()
+  })
+
+  it('validate-input multiple-conditions AND from the FurniFlow run now passes for a filled form', () => {
+    // Deployed `Record Stock Movement.validate-input` shape (after server
+    // repair): conditions[] with leftValue/rightValue keys, snake_case ops
+    // and stringified numeric rights.
+    const context = {
+      'get-type': { value: 'receipt', key: 'movementType' },
+      'get-product': { value: 'b8b7e9aa-1111-4222-8333-abcdefabcdef', key: 'productId' },
+      'get-qty': { value: 12, key: 'quantity' },
+    }
+    const config = {
+      conditionType: 'multiple-conditions',
+      logicOperator: 'AND',
+      conditions: [
+        {
+          leftValue: { type: 'workflowContext', nodeId: 'get-type', path: ['get-type', 'value'] },
+          operator: 'is_not_empty',
+        },
+        {
+          leftValue: {
+            type: 'workflowContext',
+            nodeId: 'get-product',
+            path: ['get-product', 'value'],
+          },
+          operator: 'is_not_empty',
+        },
+        {
+          leftValue: { type: 'workflowContext', nodeId: 'get-qty', path: ['get-qty', 'value'] },
+          operator: '>',
+          rightValue: '0',
+        },
+      ],
+    }
+    expect(utils.evaluateCondition(config, context)).toBe(true)
+
+    // Empty form → false (and the toast inversion scenario: is_not_empty on a
+    // missing insert id must be FALSE, not true)
+    const emptyContext = {
+      'get-type': { value: '', key: 'movementType' },
+      'get-product': { value: '', key: 'productId' },
+      'get-qty': { value: 0, key: 'quantity' },
+    }
+    expect(utils.evaluateCondition(config, emptyContext)).toBe(false)
+  })
+})

package/__tests__/runtime-template-token-resolution.test.ts

@@ -0,0 +1,225 @@
+import { generateSharedRuntimeUtilsCode } from '../src'
+import { loadHandler } from './_helpers/load-handler'
+
+// Regression guard for the literal {{...}} template tokens that deployed
+// node configs carry into the generated runtime (FurniFlow run be21af83):
+// {{urlDifferentiator}} / {{Current Page Entity.id}} / {{page.entityId}}
+// (details-page route param), {{state.X}} (trigger-time state snapshot) and
+// {{Current User.id}} (GlobalContext bridge). No other substitution site
+// exists in the generated app, so before this fix the literal token text
+// reached SQL — breaking every edit/delete/save workflow on details pages.
+
+const SENTINEL = '__TQ_UNRESOLVED_ROUTE_PARAM__'
+
+type SharedUtils = {
+  resolveConfig: (cfg: unknown, ctx: Record<string, unknown>) => any
+  resolveTemplateTokenString: (
+    value: unknown,
+    ctx: Record<string, unknown>
+  ) => { matched: boolean; value?: unknown }
+  finalizeResolvedConfig: (nodeType: string, cfg: unknown) => string | null
+  executeNodes: (
+    nodes: unknown[],
+    edges: unknown[],
+    ctx: Record<string, unknown>,
+    handlers: Record<string, unknown>,
+    workflowConfig: Record<string, unknown>
+  ) => Promise<void>
+}
+
+function loadSharedRuntime(): SharedUtils {
+  const src = generateSharedRuntimeUtilsCode()
+  const wrapper: { exports: Record<string, unknown> } = { exports: {} }
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval
+  new Function('module', 'exports', src)(wrapper, wrapper.exports)
+  return wrapper.exports as unknown as SharedUtils
+}
+
+describe('workflow runtime template-token resolution', () => {
+  const utils = loadSharedRuntime()
+
+  describe('{{state.X}}', () => {
+    it('resolves from the trigger-time state snapshot', () => {
+      const ctx = { __stateValues: { searchQuery: 'oak desk' } }
+      const resolved = utils.resolveConfig(
+        { filters: [{ field: 'name', value: '{{state.searchQuery}}', operator: 'ILIKE' }] },
+        ctx
+      )
+      expect(resolved.filters[0].value).toBe('oak desk')
+    })
+
+    it('resolves nested paths and degrades a missing state to null', () => {
+      const ctx = { __stateValues: { form: { qty: 3 } } }
+      expect(utils.resolveTemplateTokenString('{{state.form.qty}}', ctx)).toEqual({
+        matched: true,
+        value: 3,
+      })
+      expect(utils.resolveTemplateTokenString('{{state.missing}}', ctx)).toEqual({
+        matched: true,
+        value: null,
+      })
+    })
+
+    it('does NOT touch JS-expression tokens (ternaries etc.)', () => {
+      const ternary = "{{state.categorySelect === 'All' ? undefined : state.categorySelect}}"
+      expect(utils.resolveTemplateTokenString(ternary, {}).matched).toBe(false)
+    })
+  })
+
+  describe('{{urlDifferentiator}} / {{Current Page Entity.id}} / {{page.entityId}}', () => {
+    const routeCtx = {
+      __routeParams: { id: 'b8b7e9aa-1111-4222-8333-abcdefabcdef' },
+      __dynamicRouteParam: 'id',
+    }
+
+    it.each(['{{urlDifferentiator}}', '{{Current Page Entity.id}}', '{{page.entityId}}'])(
+      'resolves %s to the dynamic-route param value',
+      (token) => {
+        const resolved = utils.resolveConfig(
+          { filters: [{ field: 'id', value: token, operator: '=' }] },
+          routeCtx
+        )
+        expect(resolved.filters[0].value).toBe('b8b7e9aa-1111-4222-8333-abcdefabcdef')
+      }
+    )
+
+    it('falls back to the "id" param when no __dynamicRouteParam is declared', () => {
+      const ctx = { __routeParams: { id: 'abc-123' } }
+      expect(utils.resolveTemplateTokenString('{{urlDifferentiator}}', ctx)).toEqual({
+        matched: true,
+        value: 'abc-123',
+      })
+    })
+
+    it('resolves to the sentinel on a page with no route params', () => {
+      expect(utils.resolveTemplateTokenString('{{Current Page Entity.id}}', {})).toEqual({
+        matched: true,
+        value: SENTINEL,
+      })
+    })
+  })
+
+  describe('{{Current User.id}}', () => {
+    it('resolves from the GlobalContext-bridged currentUser', () => {
+      const ctx = { __stateValues: { currentUser: { id: 'user-42', email: 'a@b.c' } } }
+      const resolved = utils.resolveConfig(
+        { columnMappings: [{ column: 'created_by_user_id', value: '{{Current User.id}}' }] },
+        ctx
+      )
+      expect(resolved.columnMappings[0].value).toBe('user-42')
+    })
+
+    it('resolves to null when no session exists', () => {
+      expect(utils.resolveTemplateTokenString('{{Current User.id}}', {})).toEqual({
+        matched: true,
+        value: null,
+      })
+    })
+  })
+
+  describe('finalizeResolvedConfig', () => {
+    it('turns an unresolved route param in a data-node filter into a validation error', () => {
+      const cfg = { filters: [{ field: 'id', value: SENTINEL, operator: '=' }] }
+      const error = utils.finalizeResolvedConfig('data-select', cfg)
+      expect(error).toContain('id')
+      expect(error).toContain('not available')
+      expect(cfg.filters[0].value).toBeNull()
+    })
+
+    it('degrades an unresolved route param outside filters to null without erroring', () => {
+      const cfg = { columnMappings: [{ column: 'product_id', value: SENTINEL }] }
+      expect(utils.finalizeResolvedConfig('data-create-item', cfg)).toBeNull()
+      expect(cfg.columnMappings[0].value).toBeNull()
+    })
+
+    it('leaves configs without sentinels untouched', () => {
+      const cfg = { filters: [{ field: 'id', value: null, operator: '=' }] }
+      expect(utils.finalizeResolvedConfig('data-select', cfg)).toBeNull()
+      expect(cfg.filters[0].value).toBeNull()
+    })
+  })
+
+  describe('executeNodes routes the validation error to the workflow error handler', () => {
+    it('throws (→ error handler) instead of calling the data handler with the literal', async () => {
+      const handlerCalls: unknown[] = []
+      const handlers = {
+        'data-select': async (cfg: unknown) => {
+          handlerCalls.push(cfg)
+          return { rows: [] }
+        },
+      }
+      const nodes = [
+        {
+          id: 'fetch-product-data',
+          type: 'data-select',
+          stepNumber: 1,
+          config: {
+            tableName: 'products',
+            filters: [{ field: 'id', value: '{{urlDifferentiator}}', operator: '=' }],
+          },
+        },
+      ]
+      // No route params in context → the token resolves to the sentinel.
+      await expect(
+        utils.executeNodes(nodes, [], {}, handlers, { triggerNodeId: 't' })
+      ).rejects.toThrow(/not available/)
+      expect(handlerCalls).toHaveLength(0)
+    })
+  })
+
+  describe('generated data-node handlers reject the sentinel defensively', () => {
+    // The API-route segment executor resolves configs without the
+    // executeNodes finalize pass, so the handlers themselves must catch a
+    // sentinel that slipped through.
+    it('data-select returns an error result for a sentinel filter', async () => {
+      const handler = loadHandler('data-select')
+      const result = await handler(
+        { tableName: 'products', filters: [{ field: 'id', value: SENTINEL, operator: '=' }] },
+        {}
+      )
+      expect(result.error).toContain('not available')
+      expect(result.rows).toEqual([])
+    })
+
+    it('data-update-item returns an error result for a sentinel filter', async () => {
+      const handler = loadHandler('data-update-item')
+      const result = await handler(
+        {
+          tableName: 'products',
+          filters: [{ field: 'id', value: SENTINEL, operator: '=' }],
+          columnMappings: [{ column: 'name', value: 'X' }],
+        },
+        {}
+      )
+      expect(result.error).toContain('not available')
+      expect(result.updatedCount).toBe(0)
+    })
+
+    it('data-create-item nulls sentinel columnMappings so the INSERT survives', async () => {
+      const fetchMock = jest.fn(async () => ({
+        ok: true,
+        json: async () => ({ id: 'new-id', item: { id: 'new-id' } }),
+      }))
+      const originalFetch = (globalThis as any).fetch
+      ;(globalThis as any).fetch = fetchMock
+      try {
+        const handler = loadHandler('data-create-item')
+        const result = await handler(
+          {
+            tableName: 'stock_movements',
+            columnMappings: [
+              { column: 'movement_type', value: 'receipt' },
+              { column: 'product_id', value: SENTINEL },
+            ],
+          },
+          {}
+        )
+        expect(result.id).toBe('new-id')
+        const body = JSON.parse((fetchMock.mock.calls[0] as any[])[1].body)
+        expect(body.columnMappings[1].value).toBeNull()
+      } finally {
+        ;(globalThis as any).fetch = originalFetch
+      }
+    })
+  })
+})