@@ -0,0 +1,23 @@
+---
+'@objectstack/runtime': patch
+---
+
+fix(runtime)!: the flow trigger door refuses a `params` that is not a JSON object, instead of running the flow with an empty bag
+
+`POST /api/v1/automation/:name/trigger`, its legacy spelling `POST /api/v1/automation/trigger/:name` (the route `client.automation.trigger()` calls), and every declared `type: 'flow'` API endpoint build the flow's context the same way. That build read `params` only when it was a truthy object. A string such as `{"params":"oops"}` became an empty params bag, and the flow ran with no inputs: it failed later with a misleading `400 FLOW_FAILED` "Unknown variable", or succeeded doing the wrong thing. An array was spread into an index-keyed bag (`{ "0": 1, "1": 2 }`). A falsy value (`null`, `0`, `false`, `""`) was read as an absent `params`, so the body's other top-level keys were forwarded as params instead.
+
+These doors now answer `400 VALIDATION_FAILED` with one `fields[]` entry, `{ field: 'params', code: 'invalid_type' }`, whose message names the type received. The refusal comes before the flow is dispatched, so no run starts and no run row is written. It is the refusal the resume door already gives a non-object `inputs`, `variables` or `output`, and both doors now ask the question through one check, so their wording is the same.
+
+Unchanged: an object `params` (an empty one included) builds the same bag as before, a body with no `params` key still forwards its other top-level keys as params, and an empty body still runs with an empty bag. An unknown flow still answers `404`, and a caller the flow refuses still answers `403`, before the body is judged.
+
+Clause-②: no (narrowing) — the trigger doors refuse request shapes they used to dispatch: a `params` that is a string, number, boolean, array or `null`. Nothing is widened.
+
+Metadata-protocol: none (an HTTP request body's handling at the trigger doors; nothing a metadata author writes changes)
+
+<!-- adr-0087: not-required (no-migration-prescription) No metadata moves: no spec key, authorable spelling, object definition, stored row or stored shape is added, removed, renamed or re-shaped, and no exported declaration is removed or narrowed, so there is nothing for `objectstack migrate meta` to rewrite. What changes is how the flow trigger doors handle a request body whose `params` is not a JSON object: it is refused instead of dropped. The remedy is a request edit (send `params` as an object, or leave it out), never a rewrite of a package source or a stored row. The other categories are closed on facts: the package publishes (not unpublished); no ADR-0087 id is named or touched (not registered or already-registered); and nothing exported is removed or narrowed (not runtime-interface-only, type-surface-only or runtime-export-retired). -->
+
+**BREAKING** for a caller that sent `params` as something other than an object and relied on the flow running anyway, shipped as `patch` because the metadata protocol does not move.
+
+- **Before.** A non-object `params` was dropped (or, for `null` and the other falsy values, replaced by the body's other keys), and the flow was dispatched.
+- **Now.** The request is refused with `400 VALIDATION_FAILED` naming `params`, and nothing runs.
+- **Fix.** Send `params` as an object of flow input names to values, for example `{"params":{"ownerId":"u1"}}`, or leave the key out.
@@ -0,0 +1,200 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #25821 — the trigger door refuses a `params` that is not a JSON object.
+ *
+ * `buildAutomationContext` read `params` with
+ * `ctxBody.params && typeof ctxBody.params === 'object' ? { ...ctxBody.params } : {}`,
+ * so a mis-shaped value never reached the flow and never reached the caller
+ * either:
+ *
+ *  - a string (`{"params":"oops"}`) became an EMPTY bag and the flow ran with
+ *    no inputs — measured on a stock showcase boot as `400 FLOW_FAILED`
+ *    "Unknown variable: ownerId", and as `200` for a flow that needs none;
+ *  - an array passed the `typeof` guard and was spread into an index-keyed
+ *    bag (`{ "0": 1, "1": 2 }`);
+ *  - a falsy value (`null`, `0`, `false`, `""`) fell into the flat-body
+ *    back-compat branch, which forwarded the body's OTHER keys as params.
+ *
+ * The resume door already refuses the same value-shape class on its own
+ * object-valued keys (#9416), so the two doors of one engine disagreed. The
+ * trigger door now asks the resume door's question through the same function
+ * (`objectValueFailure`, `domains/automation.ts`) and answers the same
+ * refusal: `400 VALIDATION_FAILED`, one `fields[]` entry naming `params` with
+ * `invalid_type`, before dispatch — `execute()` is never called, so no run row
+ * exists. `null` is refused too, as the resume door refuses `{"inputs":null}`.
+ *
+ * Three doors share the builder and all three are driven here: both spellings
+ * of the REST trigger route, and a declared `type: 'flow'` endpoint
+ * (`endpoint-executor.ts`, #5040 E5). BOTH directions are pinned, because a
+ * door that refuses everything ships just as green as a correct one: every
+ * refused shape answers the envelope with `execute` never called, AND every
+ * accepted body still reaches `execute` with the params bag it always did.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+
+import { HttpDispatcher } from '../http-dispatcher.js';
+import { validationFailureDetails, VALIDATION_FAILED_STATUS } from '../validation-failure.js';
+import { buildEndpointExecutionContext, executeEndpointTarget } from '../endpoint-executor.js';
+import { ApiEndpointSchema } from '@objectstack/spec/api';
+import type { ApiEndpointMatch } from '@objectstack/spec/contracts';
+import type { ExecutionContext } from '@objectstack/spec/kernel';
+
+const FLOW = 'showcase_notify_owner';
+
+function makeDispatcher() {
+    const execute = vi.fn(async () => ({ success: true, output: {} }));
+    const getFlow = vi.fn(async (name: string) => (name === FLOW ? { name } : null));
+    const services: Record<string, unknown> = { automation: { execute, getFlow } };
+    const resolve = (name: string) => services[name];
+    const kernel: any = {
+        getService: resolve,
+        getServiceAsync: async (name: string) => resolve(name),
+        context: { getService: resolve },
+    };
+    return { dispatcher: new HttpDispatcher(kernel), execute };
+}
+
+const CTX = () => ({ request: {}, executionContext: { userId: 'user_1' } } as any);
+
+/** Both spellings of the REST trigger door. */
+const ROUTES: Array<{ label: string; path: string }> = [
+    { label: 'POST /:name/trigger', path: `/${FLOW}/trigger` },
+    { label: 'legacy POST /trigger/:name', path: `/trigger/${FLOW}` },
+];
+
+/** The value shapes the card measured, plus the falsy ones that took the flat-body branch. */
+const NON_OBJECTS: Array<[string, unknown, string]> = [
+    ['a string', 'oops', 'a string'],
+    ['an empty string', '', 'a string'],
+    ['an array', [1, 2], 'an array'],
+    ['an empty array', [], 'an array'],
+    ['a number', 42, 'a number'],
+    ['zero', 0, 'a number'],
+    ['a boolean', true, 'a boolean'],
+    ['false', false, 'a boolean'],
+    ['null', null, 'null'],
+];
+
+/**
+ * Drive a REST trigger door and report the refusal as the wire would: the
+ * status both dispatcher error exits derive for a thrown validation failure
+ * carrying no `.status` of its own (#3918) — the derivation the resume door's
+ * value-shape suite reads the same way.
+ */
+async function refusalFor(path: string, body: unknown) {
+    const { dispatcher, execute } = makeDispatcher();
+    let thrown: unknown;
+    let response: unknown;
+    try {
+        response = (await dispatcher.handleAutomation(path, 'POST', body, CTX())).response;
+    } catch (e) {
+        thrown = e;
+    }
+    expect(
+        thrown,
+        `trigger body ${JSON.stringify(body)} was dispatched (answered ${JSON.stringify(response)}) instead of refused`,
+    ).toBeDefined();
+    const details = validationFailureDetails(thrown);
+    const status =
+        typeof (thrown as any)?.status === 'number' ? (thrown as any).status
+        : details ? VALIDATION_FAILED_STATUS
+        : 500;
+    return { details, status, message: (thrown as Error).message, execute };
+}
+
+describe('#25821 — the REST trigger door refuses a non-object `params` before dispatch', () => {
+    for (const route of ROUTES) {
+        describe(route.label, () => {
+            it.each(NON_OBJECTS)('refuses %s — 400 VALIDATION_FAILED naming `params`, no run', async (_label, value, received) => {
+                const r = await refusalFor(route.path, { params: value });
+                expect(r.status).toBe(VALIDATION_FAILED_STATUS);
+                expect(r.details?.code).toBe('VALIDATION_FAILED');
+                // Located: `params` is named with the ADR-0114 catalog code, and
+                // the expected and received types are both stated.
+                expect(r.details?.fields).toMatchObject([{ field: 'params', code: 'invalid_type' }]);
+                expect((r.details?.fields[0] as any).message).toMatch(/expected an object/);
+                expect((r.details?.fields[0] as any).message).toContain(`received ${received}`);
+                expect(r.message).toMatch(/`params`/);
+                // Before dispatch: the engine was never asked, so no run row exists.
+                expect(r.execute).not.toHaveBeenCalled();
+            });
+
+            it('refuses a non-object `params` even when the body carries flat keys the old branch forwarded', async () => {
+                // `{"params":null,"ownerId":"u1"}` used to run with `{ ownerId: 'u1' }`
+                // — the flat-body branch read the falsy `params` as absent.
+                const r = await refusalFor(route.path, { params: null, ownerId: 'u1' });
+                expect(r.details?.fields).toMatchObject([{ field: 'params', code: 'invalid_type' }]);
+                expect(r.execute).not.toHaveBeenCalled();
+            });
+        });
+    }
+});
+
+describe('#25821 — the accepted shapes still reach the engine unchanged', () => {
+    const ACCEPTED: Array<[string, unknown, Record<string, unknown>]> = [
+        ['an object `params`', { params: { ownerId: 'u1' } }, { ownerId: 'u1' }],
+        ['an empty object `params`', { params: {} }, {}],
+        ['no `params` key — the flat body is forwarded', { ownerId: 'u1' }, { ownerId: 'u1' }],
+        ['an empty body', {}, {}],
+        ['no body at all', undefined, {}],
+        ['a record launch', { recordId: 'r1', objectName: 'crm_lead', params: { note: 'x' } },
+            { note: 'x', recordId: 'r1', crmLeadId: 'r1' }],
+    ];
+
+    for (const route of ROUTES) {
+        it.each(ACCEPTED)(`${route.label}: %s`, async (_label, body, params) => {
+            const { dispatcher, execute } = makeDispatcher();
+            const result = await dispatcher.handleAutomation(route.path, 'POST', body, CTX());
+            expect(result.response?.status).toBe(200);
+            expect(execute).toHaveBeenCalledTimes(1);
+            expect((execute.mock.calls[0] as any)[1].params).toEqual(params);
+        });
+    }
+});
+
+describe('#25821 — a declared `type: flow` endpoint, which shares the builder, refuses the same way', () => {
+    const EC = { userId: 'user-1' } as ExecutionContext;
+    const endpoint = ApiEndpointSchema.parse({
+        name: 'notify_owner',
+        path: '/api/v1/apps/showcase/notify-owner',
+        method: 'POST',
+        type: 'flow',
+        target: FLOW,
+    });
+
+    function contextFor(body: unknown) {
+        const match: ApiEndpointMatch = { endpoint, params: {} };
+        return buildEndpointExecutionContext({
+            request: { method: 'POST', path: endpoint.path, query: {}, headers: {}, body },
+            match,
+            executionContext: EC,
+            environmentId: 'env-7',
+            dataDriver: {},
+        });
+    }
+
+    it.each(NON_OBJECTS)('refuses %s — 400 VALIDATION_FAILED naming `params`, no run', async (_label, value) => {
+        const execute = vi.fn().mockResolvedValue({ success: true });
+        const answer = await executeEndpointTarget(contextFor({ params: value }), {
+            callData: vi.fn(),
+            automationService: { execute },
+        });
+        const body: any = answer.body;
+        expect(answer.status).toBe(400);
+        expect(body.error.code).toBe('VALIDATION_FAILED');
+        expect(body.error.details.fields).toMatchObject([{ field: 'params', code: 'invalid_type' }]);
+        expect(execute).not.toHaveBeenCalled();
+    });
+
+    it('still dispatches an object `params` with the bag it always built', async () => {
+        const execute = vi.fn().mockResolvedValue({ success: true });
+        const answer = await executeEndpointTarget(contextFor({ params: { ownerId: 'u1' } }), {
+            callData: vi.fn(),
+            automationService: { execute },
+        });
+        expect(answer.status).toBe(200);
+        expect(execute.mock.calls[0]![1].params).toEqual({ ownerId: 'u1' });
+    });
+});
@@ -79,6 +79,38 @@ import { carryForwardRedactedValues, redactMetadataItem } from '@objectstack/met
 // the `protocol` service at request time, never re-derived here.
 import type { ObjectStackProtocolImplementation } from '@objectstack/metadata-protocol';
 
+/**
+ * [#9416, #25821] The value-shape check for a body key whose value must be a
+ * JSON object (a map of names to values): the resume door's `inputs`,
+ * `variables` and `output`, and the trigger door's `params`. ONE function, so
+ * the two doors of one engine ask the same question and answer it in the same
+ * words — a second spelling of it is how they disagreed.
+ *
+ * Returns the located `fields[]` entry (ADR-0114 `invalid_type`) for a value
+ * that is not an object, `undefined` otherwise. `undefined` counts as ABSENT,
+ * never mis-shaped: `JSON.stringify` drops such a key, so no HTTP caller can
+ * send one, and the in-process spelling `{ key: maybeUndefined }` means "not
+ * sent". An explicit `null` IS refused — JSON can express it, and it is the
+ * value that used to be dropped most quietly of all.
+ *
+ * The received-type wording is spelled here rather than borrowed from the
+ * resume arm's `jsonTypeOf`, whose note keeps that namer local to the arm: what
+ * is shared is this one refusal, not a formatter.
+ */
+function objectValueFailure(
+    field: string,
+    value: unknown,
+): { field: string; code: 'invalid_type'; message: string } | undefined {
+    if (value === undefined) return undefined;
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) return undefined;
+    const received = value === null ? 'null' : Array.isArray(value) ? 'an array' : `a ${typeof value}`;
+    return {
+        field,
+        code: 'invalid_type',
+        message: `expected an object (a map of names to values), received ${received}`,
+    };
+}
+
 /**
  * Translate a trigger request body into the canonical `AutomationContext` the
  * engine expects, and forward the caller's resolved identity.
@@ -114,9 +146,31 @@ import type { ObjectStackProtocolImplementation } from '@objectstack/metadata-pr
  * [#19846] It also states `callerParamKeys` — which keys of the params bag the
  * caller supplied, as opposed to the row id this builder seeds — so every route
  * sharing it carries the same caller-provenance signal.
+ *
+ * [#25821] A `params` that is not a JSON object is refused here, thrown as the
+ * validation failure both dispatcher exits and the endpoint executor answer as
+ * `400 VALIDATION_FAILED` + `fields[]`. Every door that builds its context here
+ * calls this before `execute()`, so a refused trigger dispatches nothing and
+ * leaves no run row. See {@link objectValueFailure}.
  */
 export function buildAutomationContext(body: any, context: HttpProtocolContext): Record<string, unknown> {
     const ctxBody = body && typeof body === 'object' ? body : {};
+    // [#25821] The params bag must be an object before anything is read from
+    // it. The read below used to be `params && typeof params === 'object'`, so
+    // a string became an EMPTY bag and the flow ran with no inputs, an array
+    // was spread into an index-keyed bag, and a falsy value (`null`, `0`,
+    // `false`, `""`) took the flat-body branch, which forwarded the body's
+    // other keys instead. The resume door refuses the same class on its own
+    // object-valued keys (#9416); this asks its question through the same
+    // function. `undefined` is absent, as there — the flat-body branch below
+    // still serves a body with no `params` key.
+    const paramsFailure = objectValueFailure('params', ctxBody.params);
+    if (paramsFailure) {
+        throw validationFailure(
+            `Invalid trigger body — \`params\` ${paramsFailure.message}`,
+            [paramsFailure],
+        );
+    }
     // `{recordId, objectName, params}` (the UI/SDK request shape) → the
     // canonical AutomationContext shape:
     //  - `recordId` is exposed in `params.recordId` AND aliased to
@@ -125,13 +179,11 @@ export function buildAutomationContext(body: any, context: HttpProtocolContext):
     //  - `objectName` maps to the canonical `object` field.
     const recordId = ctxBody.recordId;
     const objectName = ctxBody.objectName ?? ctxBody.object;
-    const baseParams: Record<string, any> = (ctxBody.params && typeof ctxBody.params === 'object')
-        ? { ...ctxBody.params }
-        : {};
+    const baseParams: Record<string, any> = ctxBody.params !== undefined ? { ...ctxBody.params } : {};
     // Back-compat: when callers POST a flat body (no `params` wrapper),
     // forward unknown top-level keys as flow params so the original
     // `{ foo: 'bar' }` payload is not silently dropped.
-    if (!ctxBody.params) {
+    if (ctxBody.params === undefined) {
         const reserved = new Set(['recordId', 'objectName', 'object', 'event', 'params']);
         for (const [k, v] of Object.entries(ctxBody)) {
             if (reserved.has(k)) continue;
@@ -3352,17 +3404,13 @@ export async function handleAutomationRequest(deps: DomainHandlerDeps, path: str
                 // commit a4331227b pinned; before `resume()`, so nothing reaches the
                 // engine until the body is legal and the suspension stays
                 // intact for a corrected retry.
+                //
+                // The object-valued keys go through `objectValueFailure`, the
+                // one check the trigger door's `params` asks too (#25821).
                 const valueFailures: Array<{ field: string; code: 'invalid_type'; message: string }> = [];
                 for (const key of ['inputs', 'variables', 'output']) {
-                    const v = b[key];
-                    if (v === undefined) continue;
-                    if (v === null || typeof v !== 'object' || Array.isArray(v)) {
-                        valueFailures.push({
-                            field: key,
-                            code: 'invalid_type',
-                            message: `expected an object (a map of names to values), received ${jsonTypeOf(v)}`,
-                        });
-                    }
+                    const failure = objectValueFailure(key, b[key]);
+                    if (failure) valueFailures.push(failure);
                 }
                 if (b.branchLabel !== undefined && typeof b.branchLabel !== 'string') {
                     valueFailures.push({