From 5aaa6e39fd3f5a207d34d095f3acc72cc518ecf3 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 09:06:57 +0000 Subject: [PATCH 1/2] docs(spec): dialect table's cron row names what fires a schedule, not cron-parser The `## Dialects` table in the Expression Protocol docblock named `cron-parser` as the cron engine. That package is not a dependency of any package in the repo; the library that fires a schedule is `croner`, reached only from `CronSchedule.expression` via `toBoundaryJobSchedule` and `CronJobAdapter`. No cron syntax is judged at parse time, the other cron-typed slots reach no engine, and formula's registered cron engine has no caller outside its package. The row and one sentence under the table now say so; the generated reference page follows in the regeneration commit. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01M59rPZZFzqhfMUPFqqZTkf --- .changeset/cron-dialect-row-names-croner.md | 7 +++++++ packages/spec/src/shared/expression.zod.ts | 8 +++++++- 2 files changed, 14 insertions(+), 1 deletion(-) create mode 100644 .changeset/cron-dialect-row-names-croner.md diff --git a/.changeset/cron-dialect-row-names-croner.md b/.changeset/cron-dialect-row-names-croner.md new file mode 100644 index 0000000000..722418f529 --- /dev/null +++ b/.changeset/cron-dialect-row-names-croner.md @@ -0,0 +1,7 @@ +--- +"@objectstack/spec": patch +--- + +The Expression Protocol dialect table no longer names `cron-parser` as the `cron` engine. That package is not a dependency of any ObjectStack package; the row shipped to authors through the generated reference page (`content/docs/references/shared/expression.mdx`) and pointed them at the wrong library for field counts, alias vocabulary and second-field semantics. + +The row now says what the code does: no cron syntax is judged at parse time; `croner` evaluates a cron expression only when `CronSchedule.expression` is scheduled (`toBoundaryJobSchedule` → `CronJobAdapter`, where an invalid pattern is refused); every other cron-typed slot is parsed and reaches no engine; and `@objectstack/formula`'s registered `cron` engine has no caller outside that package. Documentation only — no schema, accept set or behaviour changes. diff --git a/packages/spec/src/shared/expression.zod.ts b/packages/spec/src/shared/expression.zod.ts index 66e8875cb1..3585ebab74 100644 --- a/packages/spec/src/shared/expression.zod.ts +++ b/packages/spec/src/shared/expression.zod.ts @@ -19,9 +19,15 @@ import { z } from 'zod'; * | dialect | engine | use | * |:---|:---|:---| * | `cel` | `@objectstack/formula` (cel-js + ObjectStack stdlib) | formulas, predicates, seed dynamic values | - * | `cron` | `cron-parser` | job schedules | + * | `cron` | none at parse time — `croner` fires it at schedule time, on the one wired slot | job schedules | * | `template` | `{{var}}` interpolation at evaluate time (same variable scope as CEL) | notification subjects/bodies, `titleFormat`, prompt templates | * + * No cron syntax is judged at parse time: `croner` evaluates a cron slot only + * when `CronSchedule.expression` is scheduled (`toBoundaryJobSchedule` → + * `CronJobAdapter`, where an invalid pattern is refused); every other + * cron-typed slot is parsed and reaches no engine, and `@objectstack/formula`'s + * registered `cron` engine has no caller outside that package. + * * Those three are the whole list — it is exactly the `ExpressionDialect` enum * below. Procedural JavaScript is **not** a dialect: it is the L2 authoring * surface, the sandboxed, capability-gated `ScriptBody { language: 'js' }` in From 93429c1c2f450ee9a675d5024b7607045626a186 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 5 Sep 2026 09:12:43 +0000 Subject: [PATCH 2/2] docs(spec): regenerate the Expression reference page from the corrected dialect table Produced by `pnpm --filter @objectstack/spec gen:docs`; the only file the generator changed. The page's cron row and the sentence under the table now match the docblock. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01M59rPZZFzqhfMUPFqqZTkf --- content/docs/references/shared/expression.mdx | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/content/docs/references/shared/expression.mdx b/content/docs/references/shared/expression.mdx index 932b4103c5..4bb007e306 100644 --- a/content/docs/references/shared/expression.mdx +++ b/content/docs/references/shared/expression.mdx @@ -21,9 +21,15 @@ envelope. | dialect | engine | use | |:---|:---|:---| | `cel` | `@objectstack/formula` (cel-js + ObjectStack stdlib) | formulas, predicates, seed dynamic values | -| `cron` | `cron-parser` | job schedules | +| `cron` | none at parse time — `croner` fires it at schedule time, on the one wired slot | job schedules | | `template` | `{{var}}` interpolation at evaluate time (same variable scope as CEL) | notification subjects/bodies, `titleFormat`, prompt templates | +No cron syntax is judged at parse time: `croner` evaluates a cron slot only +when `CronSchedule.expression` is scheduled (`toBoundaryJobSchedule` → +`CronJobAdapter`, where an invalid pattern is refused); every other +cron-typed slot is parsed and reaches no engine, and `@objectstack/formula`'s +registered `cron` engine has no caller outside that package. + Those three are the whole list — it is exactly the `ExpressionDialect` enum below. Procedural JavaScript is **not** a dialect: it is the L2 authoring surface, the sandboxed, capability-gated `ScriptBody { language: 'js' }` in