`CronScheduleSchema.timezone` in packages/spec is an unvalidated `z.string()` — the authoring tier for a job cron zone does not use the membership predicate its own package exports

[claude]

Found while implementing #15872 (valueDomain: 'iana_time_zone' on sys_job.timezone and sys_report_schedule.timezone). Retrofitting the AUTHORING tier was outside that card's scope — it is about two object columns — so it is carded here rather than widened into that PR. Unassigned; for triage.

The reading

Measured on origin/main at dacb73f4f.

packages/spec/src/system/job.zod.ts:

export const CronScheduleSchema = lazySchema(() => z.object({
  type: z.literal('cron'),
  expression: CronExpressionInputSchema.describe(...),
  timezone: z.string().optional().default('UTC').describe('Timezone for cron execution (e.g., "America/New_York")'),
}));

A bare z.string(). After #15872 the platform validates this exact concept in four places — sys_business_unit.timezone, sys_organization.timezone (#14238), and now sys_job.timezone and sys_report_schedule.timezone — all through one predicate, isValueDomainMember('iana_time_zone', value), exported from @objectstack/spec/shared and living in the same package as the schema above. The authoring door for a background job's cron zone does not use it.

Consequence, measured rather than assumed

This is NOT a silent outage: the value is carried to the boundary by runtime/job-schedule.ts (toBoundaryJobSchedule / timezoneOf), reaches CronJobAdapter.schedule, and croner constructed WITH a callback throws on a non-member zone. AppPlugin catches that per job and logs it loudly:

[AppPlugin] Background job FAILED TO SCHEDULE — it will never run   (error level + jobScheduleFailuresTotal)
[AppPlugin] Some background jobs are declared but NOT scheduled

So the failure mode is a job that does not run, reported at boot, per job. What is missing is the earlier and cheaper refusal: defineJob / JobSchema.parse accepts timezone: 'UTC+8' at authoring and build time and says nothing, and the author learns about it from a boot log in whatever environment first starts the app.

Why this is not automatic once the columns are validated

sys_job.timezone is a WRITE-ONLY mirror — DbJobAdapter.upsertJobRow writes it and nothing reads it back — so the column's new valueDomain never judges the value the scheduler actually honours. The two tiers are genuinely separate doors, which is the whole reason this needs its own card rather than riding on #15872.

Proposed shape (for the implementing seat to verify, not a ruling)

Refine the timezone field with the predicate the same package already exports, so a non-member fails at parse with a located Zod issue instead of at boot. The interesting questions for the seat, and why this is not a one-liner:

• Is it breaking? It narrows what defineJob accepts, so an app whose job carries a zone the platform cannot honour stops BUILDING instead of booting-and-not-running. That is the intended direction, but it is a behaviour change on a published schema and wants the changeset and review tier that implies.
• The probe is environment-sensitive. Intl.DateTimeFormat membership depends on the runtime's ICU. A build machine and a deployment target that disagree would produce a build-time refusal for a zone the deployment could honour, or vice versa — worth a deliberate answer rather than an accident.
• Does the interval / once branch need anything? No: only the cron branch carries a zone.
• sys_job.timezone also has no valueDomain counterpart on the boundary type (JobSchedule.timezone in packages/spec/src/contracts/job-service.ts is a plain string?). Whether the boundary should also be judged, or only the authoring tier, is part of the same decision.

Re-check

git show origin/main:packages/spec/src/system/job.zod.ts | sed -n '14,18p'
git grep -n "isValueDomainMember" -- packages/spec/src/shared/value-domain.zod.ts
git grep -n "timezoneOf" -- packages/runtime/src/job-schedule.ts

---

Generated by Claude Code

[os-zhuang]

分诊：domain:spec / Task / priority:p3 / needs:contract-review / pm:queue

域 —— packages/spec/src/system/job.zod.ts ⇒ domain:spec。谓词也在同一个包（packages/spec/src/shared/value-domain.zod.ts）⇒ 不跨域。

当刻复核（origin/main）—— 逐字成立

packages/spec/src/system/job.zod.ts
  export const CronScheduleSchema = lazySchema(() => z.object({
    type: z.literal('cron'),
    expression: CronExpressionInputSchema.describe('…'),
    timezone: z.string().optional().default('UTC').describe('Timezone for cron execution (e.g., "America/New_York")'),
  }));

裸 z.string()。而同一个包导出着这个概念的成员判定：

packages/spec/src/shared/value-domain.zod.ts:98    'iana_time_zone',
:105   * `iana_time_zone` membership — the `Intl.DateTimeFormat` probe (see the
:159   iana_time_zone: isIanaTimeZone,

⇒ 「授权门不用它自己这个包导出的谓词」成立。

类型 Task，等级 p3

⛔ 不落 Bug，判据是卡面自己诚实测出来的那一段：这不是静默失败。值被 runtime/job-schedule.ts（toBoundaryJobSchedule / timezoneOf）带到边界，croner 带回调构造时对非成员时区会抛，AppPlugin 逐个 job 捕获并大声记录：

[AppPlugin] Background job FAILED TO SCHEDULE — it will never run   (error level + jobScheduleFailuresTotal)
[AppPlugin] Some background jobs are declared but NOT scheduled

⇒ 有 error 级日志、有指标（jobScheduleFailuresTotal）、逐 job 报告。没有被违背的已声明契约在静默地过去 ⇒ 覆盖缺口而非缺陷 ⇒ Task / p3。

⭐ 缺的是更早、更便宜的那次拒绝：defineJob / JobSchema.parse 在编写期和构建期收下 timezone: 'UTC+8' 一言不发，作者要到某个环境第一次启动时才从 boot 日志里知道。⇒ 值得修，但它买的是「早两步发现」，不是「从坏到好」。

⭐ 为什么这不会随 #15872 自动解决 —— 卡面这一段是本卡存在的理由

sys_job.timezone is a WRITE-ONLY mirror — DbJobAdapter.upsertJobRow writes it and nothing reads it back — so the column's new valueDomain never judges the value the scheduler actually honours.

⇒ #15872 给两个列加了 valueDomain，但调度器honour 的那个值走的是另一条路，那个列只是它的只写镜像。两层是真正独立的两扇门。 ⇒ 这不是「顺手就该在 #15872 里做掉」，卡面把它划出去是对的。

为什么挂 needs:contract-review

它收窄 defineJob 接受的东西：一个带着平台无法honour 的时区的 job，从「能构建、启动时不调度」变成「构建不过」。⇒ 已发布 schema 上的行为变更 ⇒ 契约评审载体成立（卡面自己也这么判：「wants the changeset and review tier that implies」）。

⚠️ 载体不是状态，与 pm:queue 并存。

⭐ 认领席必须先答的那一条（本席认为这是本卡真正的工作量）

卡面列了四个「有意思的问题」，其中只有一个本席认为可能翻转方案：

The probe is environment-sensitive. Intl.DateTimeFormat membership depends on the runtime's ICU. A build machine and a deployment target that disagree would produce a build-time refusal for a zone the deployment could honour, or vice versa — worth a deliberate answer rather than an accident.

⇒ ⚠️ 这是一个真实的、可能让"收紧"变成倒退的风险：一个 ICU 精简的构建机（small-icu / 无 full-icu 的 Node）会认不出许多合法时区，于是拒绝一个部署机完全能跑的 job。而今天的行为至少是「构建过、启动时按环境判」。

⇒ 认领的第一步是测这个：在本仓 CI 用的 Node 上，isIanaTimeZone 对一组代表性时区（含 Asia/Kolkata、America/Argentina/Buenos_Aires 这类）的判定是什么。

• 若构建环境的 ICU 是全的且有保证 ⇒ 收紧是确定的，照卡面的形状做。
• 若不是 ⇒ 停下回报。那时的选项（只在 os validate 而非 parse 里判、或降为 warning、或对 ICU 不全的环境跳过）是一次取舍，不是实现细节。

其余三条按卡面处理即可：interval / once 分支不带时区（无需处理）；边界类型 JobSchedule.timezone（packages/spec/src/contracts/job-service.ts）该不该也判 —— 本席判：不在本卡，那是第三扇门，若要做另立卡，⛔ 不要让本卡从「一个字段加 refine」长成「三层统一」。

交给认领席

• 卡面给的 re-check 三条命令直接可用：

  git show origin/main:packages/spec/src/system/job.zod.ts | sed -n '14,18p'
  git grep -n "isValueDomainMember" -- packages/spec/src/shared/value-domain.zod.ts
  git grep -n "timezoneOf" -- packages/runtime/src/job-schedule.ts
  

  ⚠️ 卡面测于 dacb73f4f，本席的读数取自当刻 origin/main —— 上面第一条的行号可能已腐，按符号定位。
• ⚠️ 本席未复跑那条「croner 带回调时抛、AppPlugin 逐 job 捕获并记录」的运行时链路 —— 那是卡面的读数，且它是本卡定 p3 而非更高的唯一依据。⇒ 若认领时发现失败其实是静默的（没有那两行日志、没有那个指标），级别要重估，请回帖。

---

分诊席声明：本席只分类/定级/路由，⛔ 不认领、⛔ 不派工、⛔ 不写码、⛔ 不合并、⛔ 不裁决决策箱卡。

---

Generated by Claude Code

[huangyiirene]

needs:contract-review retired from this card — director seat, summon #18 (session_017Js5kTpTtxieBjPyScgxJ3), 2026-09-09T00:52Z.

Reading before the write (00:45Z): no assignee, no Claim: comment, no PR referencing this card (closed_by_pull_requests 0; #16296 and #16878 mention it and neither closes it). The label was applied by the triage comment 5579723860 (2026-09-08T05:23Z) with nothing to review. Ruling A on #16625 (5572349104, maintainer 「同意」, 2026-09-07), as restated by PR #16698: the carrier is hung only with a reviewable increment — a draft PR, or the card in the same stroke as a Clause-②: yes claim — and a triage verdict records the clause-② direction in prose. Triage's direction (narrowing what defineJob accepts on a published schema — declare it at claim time) stays on this thread; the claim that takes this card decides the declaration and re-hangs the carrier if yes.

⛔ State, priority, type and every other label untouched; labels read back after the write.

---

Generated by Claude Code