Skip to content

Commit bdc95ac

Browse files
committed
fix(spec): narrow the start-node sweep guard, name typed schedule aliases, restate the ADR-0087 reason
The filter refusal now fires only when `config.timeRelative` is a non-null object, the test the trigger-kind resolver routes a sweep by. A typed `{ type: 'cron', cron }` or `{ type: 'interval', every }` schedule is refused with the declared spelling named (`expression`, `intervalMs`). The changeset's ADR-0087 reason says what is true of each arm, and the release note no longer carries a FROM/TO rewrite: the parse refusal names where the key belongs. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FEkQ5oEQNYg7j3ueo5t6pV
1 parent 532b289 commit bdc95ac

3 files changed

Lines changed: 58 additions & 7 deletions

File tree

‎.changeset/31224-flow-start-config-refusals.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,15 @@ Clause-②: yes (narrowing) — `FlowSchema` refuses two start-node `config` sha
88
Metadata-protocol: narrowed
99
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).
1010

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. -->
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 on it. The filter arm refuses an undeclared key on that open-record config: the published time-relative descriptor declares filter inside timeRelative and nowhere else, so filter beside timeRelative was never a declared shape and no protocol step migrates from it (the #4277 class). The schedule arm refuses values the published ScheduleSchema refuses, or that the schedule reader reads nothing from. Each refusal message names the cure at the refused key. -->
1212

1313
**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).
1414

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' } } }`.
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`, when `config.timeRelative` is an object (the start node the engine routes as a sweep); a `timeRelative: null` start node is not judged.
1616
- **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);
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). The schema does not declare the aliases `cron` and `every` on a typed object, so the two typed aliases the reader happens to bind today, `{ type: 'cron', cron }` and `{ type: 'interval', every }`, are refused too, and the refusal names the declared spelling (`expression`, `intervalMs`). Neither occurs in objectstack or hotcrm;
1818
- 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);
1919
- accepted as before: a bare cron string, and the untyped aliases the reader takes (`{ cron }`, `{ expression }`, `{ every }`, `{ intervalMs }`, `{ at }`).
2020
- **One reading, pinned.** `flowStartScheduleReadsNothing` mirrors `normalizeSchedule` branch for branch, and `@objectstack/trigger-schedule` pins the two equal over every form either side distinguishes.
2121

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 }`.
22+
**What an author does.** Nothing for a sweep whose filter sits inside `timeRelative`, or a schedule that binds today in a form the published schema declares. For a refused shape, the parse refusal names where the key belongs, or the schedule spellings the readers take.

‎packages/spec/src/automation/flow-start-config-refusals.test.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,11 @@ describe('flow start config — `filter` beside `timeRelative` (#31224 B1)', ()
4545
expect(flowStartConfigRefusals(flowWith({ timeRelative: { ...TIME_RELATIVE, filter: { status: 'active' } } }))).toEqual([]);
4646
expect(flowStartConfigRefusals(flowWith({ triggerType: 'schedule', schedule: '0 8 * * *', filter: { a: 1 } }))).toEqual([]);
4747
});
48+
49+
it('judges no `filter` beside `timeRelative: null`: the trigger-kind resolver does not route that start node as a sweep', () => {
50+
expect(flowStartConfigRefusals(flowWith({ timeRelative: null, filter: { status: 'active' } }))).toEqual([]);
51+
expect(startIssues({ timeRelative: null, filter: { status: 'active' } })).toEqual([]);
52+
});
4853
});
4954

5055
describe('flow start config — `schedule` (#31224 B1, ruling option (a))', () => {
@@ -93,6 +98,24 @@ describe('flow start config — `schedule` (#31224 B1, ruling option (a))', () =
9398
}
9499
});
95100

101+
it('refuses the typed aliases the published ScheduleSchema does not declare, naming the declared spelling', () => {
102+
const cron = startIssues({ triggerType: 'schedule', schedule: { type: 'cron', cron: '0 8 * * *' } });
103+
expect(cron).toHaveLength(1);
104+
expect(cron[0]!.path).toBe('nodes.0.config.schedule');
105+
expect(cron[0]!.message).toMatch(/is not a schedule at `schedule\.expression`/);
106+
expect(cron[0]!.message).toMatch(/names its cron in `expression`, not `cron`/);
107+
108+
const every = startIssues({ triggerType: 'schedule', schedule: { type: 'interval', every: 60000 } });
109+
expect(every).toHaveLength(1);
110+
expect(every[0]!.path).toBe('nodes.0.config.schedule');
111+
expect(every[0]!.message).toMatch(/is not a schedule at `schedule\.intervalMs`/);
112+
expect(every[0]!.message).toMatch(/names its period in `intervalMs`, not `every`/);
113+
114+
// Without the alias key, no alias hint.
115+
const bare = flowStartConfigRefusals(flowWith({ triggerType: 'schedule', schedule: { type: 'cron' } }));
116+
expect(bare[0]!.message).not.toMatch(/not `cron`/);
117+
});
118+
96119
it('refuses a typed cron whose expression is an envelope: it passes the schema, and the reader reads nothing', () => {
97120
const found = flowStartConfigRefusals(flowWith({
98121
triggerType: 'schedule',

‎packages/spec/src/automation/flow-start-config-refusals.ts‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,11 @@ import { ScheduleSchema } from '../system/job.zod';
2626
* - an object that carries `type` is judged against the published
2727
* {@link ScheduleSchema} (the discriminant, a cron `timezone` that is a
2828
* 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;
29+
* `at`), and then, as an untyped one is, for being readable at all.
30+
* By ruling, the typed aliases the reader happens to bind
31+
* (`{ type: 'cron', cron }`, `{ type: 'interval', every }`) are refused
32+
* too, because the published schema does not declare those keys; the
33+
* refusal names the declared spelling (`expression`, `intervalMs`);
3034
* - any other value is refused only when the reader reads nothing from it
3135
* ({@link flowStartScheduleReadsNothing}). The untyped aliases the
3236
* reader accepts (`{ cron }`, `{ expression }`, `{ every }`,
@@ -76,6 +80,24 @@ export function flowStartScheduleReadsNothing(raw: unknown): boolean {
7680
return true;
7781
}
7882

83+
/**
84+
* The key a typed schedule spells another way. `normalizeSchedule` reads the
85+
* untyped aliases `cron` and `every` inside its typed branches too, but the
86+
* published {@link ScheduleSchema} declares only `expression` and
87+
* `intervalMs` on a typed object (ruling 6717636410 §2), so the refusal names
88+
* the declared spelling.
89+
*/
90+
function typedAliasHint(raw: Record<string, unknown>): string {
91+
const has = (k: string) => Object.prototype.hasOwnProperty.call(raw, k);
92+
if (raw.type === 'cron' && has('cron') && !has('expression')) {
93+
return " A typed cron schedule names its cron in `expression`, not `cron`: write `{ type: 'cron', expression: '…' }`.";
94+
}
95+
if (raw.type === 'interval' && has('every') && !has('intervalMs')) {
96+
return " A typed interval schedule names its period in `intervalMs`, not `every`: write `{ type: 'interval', intervalMs: … }`.";
97+
}
98+
return '';
99+
}
100+
79101
function scheduleRefusal(raw: unknown): string | undefined {
80102
if (raw == null || typeof raw === 'string') {
81103
return typeof raw === 'string' && flowStartScheduleReadsNothing(raw)
@@ -90,7 +112,9 @@ function scheduleRefusal(raw: unknown): string | undefined {
90112
const issue = parsed.error.issues[0];
91113
const at = issue && issue.path.length > 0 ? ` at \`schedule.${issue.path.join('.')}\`` : '';
92114
return (
93-
`The start node's \`config.schedule\` is not a schedule${at}: ${issue?.message ?? 'refused'}. The schedule ` +
115+
`The start node's \`config.schedule\` is not a schedule${at}: ${issue?.message ?? 'refused'}.` +
116+
typedAliasHint(raw) +
117+
' The schedule ' +
94118
'readers cannot use it, so a schedule flow stays unbound and a time-relative sweep falls back to daily ' +
95119
"08:00 UTC. Write `{ type: 'cron', expression: '0 8 * * *', timezone: 'UTC' }`, " +
96120
"`{ type: 'interval', intervalMs: 60000 }` or `{ type: 'once', at: '<ISO datetime>' }`, or a bare cron string."
@@ -114,7 +138,11 @@ export function flowStartConfigRefusals(flow: unknown): FlowStartConfigRefusal[]
114138
flow.nodes.forEach((node, index) => {
115139
if (!isRecord(node) || node.type !== 'start' || !isRecord(node.config)) return;
116140
const config = node.config;
117-
if (config.timeRelative !== undefined && Object.prototype.hasOwnProperty.call(config, 'filter')) {
141+
// A sweep is a start node whose `timeRelative` is a non-null object, the
142+
// exact test the trigger-kind resolver (`flow-trigger-kind.ts`) routes by,
143+
// so `timeRelative: null` is not judged as a sweep.
144+
const isSweep = config.timeRelative != null && typeof config.timeRelative === 'object';
145+
if (isSweep && Object.prototype.hasOwnProperty.call(config, 'filter')) {
118146
out.push({
119147
path: ['nodes', index, 'config', 'filter'],
120148
message:

0 commit comments

Comments
 (0)