Skip to content

Commit 532b289

Browse files
committed
fix(spec)!: refuse a start-node filter beside timeRelative and a schedule the readers cannot use
A start node's config is an open record, so the flow parse never judged two shapes that then do nothing: a `filter` beside `timeRelative` (the sweep reads `timeRelative.filter`, so the flow launches for every record in the window), and a `schedule` normalizeSchedule reads nothing from (a schedule flow stays unbound, a sweep falls back to daily 08:00 UTC). FlowSchema now refuses both, through flowStartConfigRefusals: a typed schedule object is judged against the published ScheduleSchema and then for being readable; any other value only when the reader reads nothing, so the bare cron string and the untyped aliases that bind today stay accepted. flowStartScheduleReadsNothing mirrors normalizeSchedule branch for branch, and trigger-schedule pins the two equal. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FEkQ5oEQNYg7j3ueo5t6pV
1 parent c2bc76e commit 532b289

9 files changed

Lines changed: 337 additions & 0 deletions

File tree

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
'@objectstack/spec': minor
3+
---
4+
5+
fix(spec)!: the flow parse refuses a start node's `config.filter` beside `config.timeRelative`, and a `config.schedule` the schedule readers cannot use
6+
7+
Clause-②: yes (narrowing) — `FlowSchema` refuses two start-node `config` shapes it accepted before, at every door that parses a flow; `@objectstack/spec/automation` also exports `flowStartConfigRefusals`, `flowStartScheduleReadsNothing` and the `FlowStartConfigRefusal` type.
8+
Metadata-protocol: narrowed
9+
Skills-docs: none — `skills/**` and `content/docs/**` teach `timeRelative.filter` inside the descriptor and typed `{ type: 'cron', expression }` schedules, which this accepts. The generated `skills/objectstack-automation/references/_index.md` gains the source files the flow closure now reaches (`system/job.zod.ts` and its imports).
10+
11+
<!-- adr-0087: not-required (no-migration-prescription) No key of any schema is added, removed or renamed: FlowNodeSchema.config stays an open record, and the parse now refuses two shapes no reader honoured. A start-node filter beside timeRelative was read by nothing, and a schedule the reader reads nothing from (or one the published ScheduleSchema refuses) never bound as written, so there is no rewrite that keeps what the author meant in every case; each refusal names the fix. -->
12+
13+
**BREAKING** accept-set narrowing of `FlowSchema` (every door that parses a flow: `defineStack`, `os validate` / `os build`, the metadata save door including drafts, publish, and the automation engine's registration).
14+
15+
- **`config.filter` beside `config.timeRelative`.** Before, it parsed and nothing read it: the time-relative sweep reads its row filter from `timeRelative.filter`, so the flow launched for every record in the date window. Now it is refused at `nodes[i].config.filter`. **FROM** `config: { timeRelative: { … }, filter: { status: 'active' } }` **TO** `config: { timeRelative: { …, filter: { status: 'active' } } }`.
16+
- **A `config.schedule` the readers cannot use.** Both readers (the schedule trigger, and the time-relative sweep's cadence) pass it through `normalizeSchedule`. When that reads nothing, a schedule flow stays unbound (one warn in the server log) and a sweep falls back to daily 08:00 UTC. Now, at `nodes[i].config.schedule`:
17+
- an object carrying `type` is judged against the published `ScheduleSchema` (the discriminant, a cron `timezone` that is an IANA zone, a positive integer `intervalMs`, an ISO `at`), and then for being readable at all (a cron `expression` written as an envelope is not);
18+
- any other value is refused only when the reader reads nothing from it (an empty string, `{}`, `{ cadence: 'daily' }`, a number, an array, a non-positive interval);
19+
- accepted as before: a bare cron string, and the untyped aliases the reader takes (`{ cron }`, `{ expression }`, `{ every }`, `{ intervalMs }`, `{ at }`).
20+
- **One reading, pinned.** `flowStartScheduleReadsNothing` mirrors `normalizeSchedule` branch for branch, and `@objectstack/trigger-schedule` pins the two equal over every form either side distinguishes.
21+
22+
**What an author does.** Nothing for a sweep whose filter sits inside `timeRelative`, or a schedule that binds today. For a refused shape: move the filter into `timeRelative.filter`; write the schedule as a cron string or one of `{ type: 'cron', expression, timezone? }`, `{ type: 'interval', intervalMs }`, `{ type: 'once', at }`.

‎packages/spec/api-surface/automation.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,7 @@
201201
"FlowSchema (const)",
202202
"FlowSlotRefusalCode (type)",
203203
"FlowSlotRefusalParams (interface)",
204+
"FlowStartConfigRefusal (interface)",
204205
"FlowTextSlot (interface)",
205206
"FlowTriggerKind (type)",
206207
"FlowValueSlot (type)",
@@ -346,6 +347,8 @@
346347
"flowNodeTextSlotSources (function)",
347348
"flowNodeValueTemplateRefusals (function)",
348349
"flowScreenFieldOptionKey (function)",
350+
"flowStartConfigRefusals (function)",
351+
"flowStartScheduleReadsNothing (function)",
349352
"flowTextSlotSources (function)",
350353
"getApprovalNodeConfigJsonSchema (function)",
351354
"getBuiltinNodeConfigContracts (function)",

‎packages/spec/export-origins/automation.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@
195195
"FlowSchema": "src/automation/flow.zod.ts#FlowSchema (const)",
196196
"FlowSlotRefusalCode": "src/automation/flow-node-expression-paths.ts#FlowSlotRefusalCode (type)",
197197
"FlowSlotRefusalParams": "src/automation/flow-node-expression-paths.ts#FlowSlotRefusalParams (interface)",
198+
"FlowStartConfigRefusal": "src/automation/flow-start-config-refusals.ts#FlowStartConfigRefusal (interface)",
198199
"FlowTextSlot": "src/automation/flow-text-slot-template.ts#FlowTextSlot (interface)",
199200
"FlowTriggerKind": "src/automation/flow-trigger-kind.ts#FlowTriggerKind (type)",
200201
"FlowValueSlot": "src/automation/builtin-node-config.zod.ts#FlowValueSlot (type)",
@@ -339,6 +340,8 @@
339340
"flowNodeTextSlotSources": "src/automation/flow-text-slot-template.ts#flowNodeTextSlotSources (function)",
340341
"flowNodeValueTemplateRefusals": "src/automation/flow-value-slot-template.ts#flowNodeValueTemplateRefusals (function)",
341342
"flowScreenFieldOptionKey": "src/automation/flow-screen-option-key.ts#flowScreenFieldOptionKey (function)",
343+
"flowStartConfigRefusals": "src/automation/flow-start-config-refusals.ts#flowStartConfigRefusals (function)",
344+
"flowStartScheduleReadsNothing": "src/automation/flow-start-config-refusals.ts#flowStartScheduleReadsNothing (function)",
342345
"flowTextSlotSources": "src/automation/flow-text-slot-template.ts#flowTextSlotSources (function)",
343346
"getApprovalNodeConfigJsonSchema": "src/automation/approval.zod.ts#getApprovalNodeConfigJsonSchema (function)",
344347
"getBuiltinNodeConfigContracts": "src/automation/flow-node-config-refusals.ts#getBuiltinNodeConfigContracts (function)",
Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { describe, expect, it } from 'vitest';
4+
import { FlowSchema } from './flow.zod';
5+
import { flowStartConfigRefusals, flowStartScheduleReadsNothing } from './flow-start-config-refusals';
6+
7+
const flowWith = (config: Record<string, unknown>) => ({
8+
name: 'start_config_probe',
9+
label: 'Start Config Probe',
10+
type: 'schedule',
11+
runAs: 'system',
12+
nodes: [
13+
{ id: 'start', type: 'start', label: 'Start', config },
14+
{ id: 'end', type: 'end', label: 'End' },
15+
],
16+
edges: [{ id: 'e1', source: 'start', target: 'end' }],
17+
});
18+
19+
/** The parse's issues anchored on the start node's config. */
20+
const startIssues = (config: Record<string, unknown>) => {
21+
const parsed = FlowSchema.safeParse(flowWith(config));
22+
if (parsed.success) return [];
23+
return parsed.error.issues
24+
.filter((i) => i.path[0] === 'nodes' && i.path[1] === 0 && i.path[2] === 'config')
25+
.map((i) => ({ path: i.path.join('.'), message: i.message }));
26+
};
27+
28+
const TIME_RELATIVE = {
29+
object: 'contract',
30+
dateField: 'end_date',
31+
offsetDays: -30,
32+
};
33+
34+
describe('flow start config — `filter` beside `timeRelative` (#31224 B1)', () => {
35+
it('refuses it at the parse, naming where the filter belongs', () => {
36+
const issues = startIssues({ triggerType: 'time_relative', timeRelative: TIME_RELATIVE, filter: { status: 'active' } });
37+
expect(issues).toHaveLength(1);
38+
expect(issues[0]!.path).toBe('nodes.0.config.filter');
39+
expect(issues[0]!.message).toMatch(/nothing reads it/);
40+
expect(issues[0]!.message).toMatch(/launches for every record in the date window/);
41+
expect(issues[0]!.message).toMatch(/Move it into `config\.timeRelative\.filter`/);
42+
});
43+
44+
it('accepts the filter inside `timeRelative`, and a `filter` on a start node with no `timeRelative`', () => {
45+
expect(flowStartConfigRefusals(flowWith({ timeRelative: { ...TIME_RELATIVE, filter: { status: 'active' } } }))).toEqual([]);
46+
expect(flowStartConfigRefusals(flowWith({ triggerType: 'schedule', schedule: '0 8 * * *', filter: { a: 1 } }))).toEqual([]);
47+
});
48+
});
49+
50+
describe('flow start config — `schedule` (#31224 B1, ruling option (a))', () => {
51+
it('accepts the bare cron string, the three typed forms, and the untyped aliases the reader takes', () => {
52+
for (const schedule of [
53+
'0 8 * * *',
54+
{ type: 'cron', expression: '0 8 * * *' },
55+
{ type: 'cron', expression: '0 8 * * *', timezone: 'America/New_York' },
56+
{ type: 'interval', intervalMs: 60000 },
57+
{ type: 'once', at: '2027-01-01T08:00:00Z' },
58+
{ cron: '0 8 * * *' },
59+
{ expression: '0 8 * * *' },
60+
{ every: 60000 },
61+
{ intervalMs: 60000 },
62+
{ at: '2027-01-01T08:00:00Z' },
63+
]) {
64+
expect(flowStartConfigRefusals(flowWith({ triggerType: 'schedule', schedule })), JSON.stringify(schedule)).toEqual([]);
65+
}
66+
});
67+
68+
it('refuses a typed cron whose timezone is not an IANA zone, at the parse', () => {
69+
const issues = startIssues({ triggerType: 'schedule', schedule: { type: 'cron', expression: '0 8 * * *', timezone: 'UTC+8' } });
70+
expect(issues).toHaveLength(1);
71+
expect(issues[0]!.path).toBe('nodes.0.config.schedule');
72+
expect(issues[0]!.message).toMatch(/is not a schedule at `schedule\.timezone`/);
73+
expect(issues[0]!.message).toMatch(/a schedule flow stays unbound/);
74+
});
75+
76+
it('refuses a typed form the published ScheduleSchema refuses (unknown type, non-positive interval, no expression)', () => {
77+
for (const schedule of [
78+
{ type: 'hourly' },
79+
{ type: 'interval', intervalMs: 0 },
80+
{ type: 'cron' },
81+
{ type: 'once', at: 'tomorrow' },
82+
]) {
83+
const found = flowStartConfigRefusals(flowWith({ triggerType: 'schedule', schedule }));
84+
expect(found.map((f) => f.path.join('.')), JSON.stringify(schedule)).toEqual(['nodes.0.config.schedule']);
85+
}
86+
});
87+
88+
it('refuses an untyped value the reader reads nothing from, and an empty string', () => {
89+
for (const schedule of [{ cadence: 'daily' }, {}, [], 42, true, ' ', { every: -5 }]) {
90+
const found = flowStartConfigRefusals(flowWith({ triggerType: 'schedule', schedule }));
91+
expect(found, JSON.stringify(schedule)).toHaveLength(1);
92+
expect(found[0]!.message).toMatch(/schedule flow stays unbound and a time-relative sweep falls back to daily 08:00 UTC/);
93+
}
94+
});
95+
96+
it('refuses a typed cron whose expression is an envelope: it passes the schema, and the reader reads nothing', () => {
97+
const found = flowStartConfigRefusals(flowWith({
98+
triggerType: 'schedule',
99+
schedule: { type: 'cron', expression: { dialect: 'cron', source: '0 8 * * *' } },
100+
}));
101+
expect(found).toHaveLength(1);
102+
expect(found[0]!.message).toMatch(/names no schedule the readers can use/);
103+
});
104+
105+
it('judges no absent or null schedule', () => {
106+
expect(flowStartConfigRefusals(flowWith({ triggerType: 'schedule', schedule: null }))).toEqual([]);
107+
expect(flowStartConfigRefusals(flowWith({ triggerType: 'manual' }))).toEqual([]);
108+
});
109+
110+
it('reads only top-level start nodes', () => {
111+
const flow = flowWith({ triggerType: 'manual' }) as any;
112+
flow.nodes.splice(1, 0, { id: 'mid', type: 'assignment', label: 'Mid', config: { schedule: {} } });
113+
expect(flowStartConfigRefusals(flow)).toEqual([]);
114+
});
115+
});
116+
117+
describe('flowStartScheduleReadsNothing — the reader\'s precedence', () => {
118+
it('the first candidate present decides, as `normalizeSchedule` does', () => {
119+
// `intervalMs` is present and unusable, so the reader never reaches `every`.
120+
expect(flowStartScheduleReadsNothing({ intervalMs: -1, every: 60000 })).toBe(true);
121+
expect(flowStartScheduleReadsNothing({ expression: '', cron: '0 8 * * *' })).toBe(false);
122+
expect(flowStartScheduleReadsNothing(undefined)).toBe(false);
123+
});
124+
});
Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
import { ScheduleSchema } from '../system/job.zod';
4+
5+
/**
6+
* Two start-node `config` shapes that parse and then do nothing (#31224 item
7+
* B, ruling B1 option (a)).
8+
*
9+
* A flow's start node `config` is an open record (`FlowNodeSchema.config`), so
10+
* the parse never judged these two keys, and the readers that do read them
11+
* skip what they cannot use without telling the author:
12+
*
13+
* - **`config.filter` beside `config.timeRelative`.** A time-relative sweep
14+
* reads its row filter from `timeRelative.filter` (`time-relative-trigger.ts`
15+
* in `@objectstack/trigger-schedule`); nothing reads a `filter` on the start
16+
* node's own `config`, so a sweep written that way launches the flow for
17+
* every row in the date window. Refused with the move as the prescription.
18+
*
19+
* - **A `config.schedule` the schedule readers cannot use.** Both readers
20+
* (`ScheduleTrigger` for a schedule flow, `TimeRelativeTrigger` for a sweep's
21+
* cadence) pass it through `normalizeSchedule` (`schedule-trigger.ts`). A
22+
* descriptor it reads nothing from leaves a schedule flow unbound (one warn
23+
* in the server log) and a sweep on its default daily 08:00 UTC cadence,
24+
* either way not what was written. Three readings, one per form:
25+
* - a bare cron STRING is not judged here (the reader takes it verbatim);
26+
* - an object that carries `type` is judged against the published
27+
* {@link ScheduleSchema} (the discriminant, a cron `timezone` that is a
28+
* member of `iana_time_zone`, a positive integer `intervalMs`, an ISO
29+
* `at`), and then, as an untyped one is, for being readable at all;
30+
* - any other value is refused only when the reader reads nothing from it
31+
* ({@link flowStartScheduleReadsNothing}). The untyped aliases the
32+
* reader accepts (`{ cron }`, `{ expression }`, `{ every }`,
33+
* `{ intervalMs }`, `{ at }`) run today and stay accepted.
34+
*
35+
* Top-level `start` nodes only: a start node is never a region member.
36+
*/
37+
38+
export interface FlowStartConfigRefusal {
39+
readonly path: ReadonlyArray<string | number>;
40+
readonly message: string;
41+
}
42+
43+
function isRecord(v: unknown): v is Record<string, unknown> {
44+
return !!v && typeof v === 'object' && !Array.isArray(v);
45+
}
46+
47+
/**
48+
* `true` when the flow schedule readers read NOTHING from `raw`: the exact
49+
* complement of what `normalizeSchedule` (`@objectstack/trigger-schedule`)
50+
* turns into a job schedule, which pins the two together over a table of
51+
* shapes. `null` / `undefined` read as "not declared" and answer `false`: an
52+
* absent schedule is not a written one.
53+
*/
54+
export function flowStartScheduleReadsNothing(raw: unknown): boolean {
55+
if (raw == null) return false;
56+
if (typeof raw === 'string') return raw.trim().length === 0;
57+
if (typeof raw !== 'object') return true;
58+
const s = raw as Record<string, unknown>;
59+
const type = typeof s.type === 'string' ? s.type : undefined;
60+
// Each branch is `normalizeSchedule`'s, step for step (truthiness included):
61+
// the first candidate present decides, and a decided value that is not
62+
// usable reads nothing even when a later alias would have been.
63+
if (type === 'cron' || (!type && (typeof s.cron === 'string' || typeof s.expression === 'string'))) {
64+
const expression =
65+
(typeof s.expression === 'string' && s.expression) || (typeof s.cron === 'string' && s.cron) || undefined;
66+
return !expression;
67+
}
68+
if (type === 'interval' || (!type && (typeof s.intervalMs === 'number' || typeof s.every === 'number'))) {
69+
const intervalMs =
70+
(typeof s.intervalMs === 'number' && s.intervalMs) || (typeof s.every === 'number' && s.every) || undefined;
71+
return !intervalMs || intervalMs <= 0;
72+
}
73+
if (type === 'once' || (!type && typeof s.at === 'string')) {
74+
return !(typeof s.at === 'string' && s.at);
75+
}
76+
return true;
77+
}
78+
79+
function scheduleRefusal(raw: unknown): string | undefined {
80+
if (raw == null || typeof raw === 'string') {
81+
return typeof raw === 'string' && flowStartScheduleReadsNothing(raw)
82+
? 'The start node\'s `config.schedule` is an empty string, so no schedule is read from it: a schedule ' +
83+
'flow stays unbound and a time-relative sweep falls back to daily 08:00 UTC. Write a cron expression ' +
84+
"(e.g. '0 8 * * *') or remove the key."
85+
: undefined;
86+
}
87+
if (isRecord(raw) && Object.prototype.hasOwnProperty.call(raw, 'type')) {
88+
const parsed = ScheduleSchema.safeParse(raw);
89+
if (!parsed.success) {
90+
const issue = parsed.error.issues[0];
91+
const at = issue && issue.path.length > 0 ? ` at \`schedule.${issue.path.join('.')}\`` : '';
92+
return (
93+
`The start node's \`config.schedule\` is not a schedule${at}: ${issue?.message ?? 'refused'}. The schedule ` +
94+
'readers cannot use it, so a schedule flow stays unbound and a time-relative sweep falls back to daily ' +
95+
"08:00 UTC. Write `{ type: 'cron', expression: '0 8 * * *', timezone: 'UTC' }`, " +
96+
"`{ type: 'interval', intervalMs: 60000 }` or `{ type: 'once', at: '<ISO datetime>' }`, or a bare cron string."
97+
);
98+
}
99+
}
100+
if (!flowStartScheduleReadsNothing(raw)) return undefined;
101+
return (
102+
'The start node\'s `config.schedule` names no schedule the readers can use (a cron `expression` as a ' +
103+
'string, a positive `intervalMs`, or an `at` datetime), so a schedule flow stays unbound and a ' +
104+
'time-relative sweep falls back to daily 08:00 UTC. Write a cron string such as \'0 8 * * *\', or ' +
105+
"`{ type: 'cron', expression: '0 8 * * *' }`, `{ type: 'interval', intervalMs: 60000 }` or " +
106+
"`{ type: 'once', at: '<ISO datetime>' }`."
107+
);
108+
}
109+
110+
/** The refusals of every top-level start node's `config` in `flow`. */
111+
export function flowStartConfigRefusals(flow: unknown): FlowStartConfigRefusal[] {
112+
if (!isRecord(flow) || !Array.isArray(flow.nodes)) return [];
113+
const out: FlowStartConfigRefusal[] = [];
114+
flow.nodes.forEach((node, index) => {
115+
if (!isRecord(node) || node.type !== 'start' || !isRecord(node.config)) return;
116+
const config = node.config;
117+
if (config.timeRelative !== undefined && Object.prototype.hasOwnProperty.call(config, 'filter')) {
118+
out.push({
119+
path: ['nodes', index, 'config', 'filter'],
120+
message:
121+
'The start node declares `config.filter` beside `config.timeRelative`, and nothing reads it: a ' +
122+
'time-relative sweep takes its row filter from `timeRelative.filter`, so as written the flow ' +
123+
'launches for every record in the date window. Move it into `config.timeRelative.filter`.',
124+
});
125+
}
126+
if (Object.prototype.hasOwnProperty.call(config, 'schedule')) {
127+
const message = scheduleRefusal(config.schedule);
128+
if (message) out.push({ path: ['nodes', index, 'config', 'schedule'], message });
129+
}
130+
});
131+
return out;
132+
}

‎packages/spec/src/automation/flow.zod.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import { predicateSlotRefusal, resolveFlowNodeExpressions, type FlowNodeSiblingB
2828
import { flowNodeConfigRefusals } from './flow-node-config-refusals';
2929
import { apiTriggerSecretRefRefusals } from './api-trigger-secret-ref.zod';
3030
import { apiTriggerSignatureRefusals } from './api-trigger-signature.zod';
31+
import { flowStartConfigRefusals } from './flow-start-config-refusals';
3132
import { saveNoticePlacementRefusals } from './save-notice-placement';
3233
// [#23543 F3] The loose `config` keys of the two sibling-block node types — one
3334
// table, shared with the two D2 lifts that still run at rehydration.
@@ -1704,6 +1705,15 @@ export const FlowSchema = lazySchema(() => strictObject(
17041705
ctx.addIssue({ code: 'custom', path: [...refusal.path], message: refusal.message });
17051706
}
17061707

1708+
// [#31224 B1] Two start-node `config` shapes that parse and then do nothing:
1709+
// a `filter` beside `timeRelative` (the sweep reads `timeRelative.filter`),
1710+
// and a `schedule` the schedule readers cannot use. Why each, and why the
1711+
// untyped aliases the reader accepts stay accepted, is
1712+
// `flow-start-config-refusals.ts`'s header.
1713+
for (const refusal of flowStartConfigRefusals(flow)) {
1714+
ctx.addIssue({ code: 'custom', path: [...refusal.path], message: refusal.message });
1715+
}
1716+
17071717
// [#28251] A `save_notice` node answers the write that fired the run, so it
17081718
// stands only in a flow a create or update record trigger starts — anywhere
17091719
// else no write waits on the run. Refused at each such node, at any region

0 commit comments

Comments
 (0)