[Decision] os build cannot lower a job's handler into the new JobSchema.body as ruling E wrote it — withdraw the build lowering (C), or change the functions contract (A) or the job handler form (B)? #21540

Ruled: 5968961157 · letter C · 2026-10-03T12:02Z

This card carries #21515's scope item 2, the build lowering. #21515 keeps the spec half, which is draft PR #21538 (Part of #21515).

Filing gate: ② a maintainer decision. Executing ruling E (5964305303 on #21489, 「jobs同意」) falsified one of its premises, so the change of part of a recorded ruling goes back to the maintainer. Filed by domain:spec seat 2 (session_01YDt3PzwfrkuFzUBF89WPmM, seat post #18549), from the #21515 dev report 5965564062 (open_questions[0]). ⛔ Not a claim. Nothing waits on this card: the spec half lands without it, and #21489's runtime binder needs only the spec half.

维护者速读

上一轮你批准「jobs 同意」(E):job 像 hook 一样带沙箱代码体 body,并由 os build 把 job 的处理函数自动转成 body。spec 那一半已做完(PR #21538:JobSchema.body、handler 标为弃用、超时只在一处声明)。自动转换这一半做不成:job 的处理函数写在 defineStack({ functions }) 里,defineStack 解析时会把每个函数包一层 zod 外壳,构建时拿到的是外壳、读不到作者源码;文档里 job 函数的标准写法 ({ jobId, ql, logger }) 即使读得到,转出来的 body 运行时也会报错,而且 body 优先,会顶掉原本能跑的函数。C＝撤回自动转换:job 的 body 直接按数据写(和 Studio、AI、JSON 包写法一致),构建只校验;A＝改 functions 的契约让构建读得到源码;B＝给 job 加 hook 那样的内联函数写法。推荐 C。要不要撤回这一项?(C／A／B)

Background

• Ruling E (5964305303): "jobs gain a sandboxed body, like hooks. The spec half is spec(system): JobSchema gains a sandboxed body, like hooks and script actions, so a job handler is declarable code that travels with a package (ruled on #21489, E) #21515. Its scope: JobSchema.body reusing the hook body shape; handler deprecated; objectstack build lowers inline job handlers into it." Facet ④: 「复用 hook 的体形与唯一绑定器,不另立机制」.
• The spec half is built in PR spec(system): JobSchema gains a sandboxed L2 body and deprecates handler; a body job has one time limit #21538 (Clause-②: yes (widening), contract review owed):
  • JobSchema.body is ScriptBodySchema by reference, L2 only. An L1 expression is refused at body.language with a reason.
  • handler is optional and DEPRECATED ("prefer body"), and a job with neither key is refused.
  • body.timeoutMs is refused on a job, and JobSchema.timeoutMs is the one statement of the limit.
  • The docs teach writing a job body as data.
• The lowering was implemented, measured and reverted. It is in the branch history at 4893a0b48b / 781609d2f7, reverted in b7cf7f78b8. PR spec(system): JobSchema gains a sandboxed L2 body and deprecates handler; a body job has one time limit #21538 touches no packages/cli file.

Governing text:

• Ruling E (above): the lowering clause is the item at issue.
• ADR-0088: a function is code, never a metadata row. That is why a JSON artifact cannot carry a job handler, and why E exists.
• automation/flow-function.zod.ts:237: "z.function() wraps callables". The docblock says the CLI lowers callables BEFORE the stack is parsed, but defineStack in the author's own config parses first (premise 2).

Premises (each with its re-check, at origin/main 49161683fb)

1. Jobs have no inline handler form. An inline function was never accepted for a job.
   • git grep -n "handler: z.string()" origin/main -- packages/spec/src/system/job.zod.ts → :193, 1 hit.
2. The callable the build sees for a functions entry is zod's wrapper, not the author's function.
   • git grep -n -E "z\.function\(" origin/main -- packages/spec/src/automation/flow-function.zod.ts → FlowFunctionDeclarationSchema.handler (:183) and FlowFunctionEntrySchema's first arm (:266).
   • Measured by the dev with the pipeline pin defineStack → normalizeStackInput → lowerCallables → ObjectStackDefinitionSchema at 781609d2f7. The parse succeeded, job.body was undefined, and the recorded extraction warning was free-identifiers [func, inst, parse]: zod's identifiers, not the author's.
3. The documented job handler form would lower into a body that throws.
   • git grep -n "JobHandlerContext" origin/main -- content/docs/automation/jobs.mdx → :156 to :170: async function sweepProjectHealth({ ql, jobId, logger }: JobHandlerContext).
   • A sandbox L2 body runs as (async (ctx) => { … }) with ctx.api / ctx.log. A destructured { ql, jobId, logger } extracts into a body reading unbound names. Because body wins over handler, it would replace a working handler.
4. Zero measured pull.
   • git grep -l -E "^\s*jobs\s*:" origin/main -- 'examples/**/*.ts' 'packages/apps/**/*.ts' → examples/app-showcase/objectstack.config.ts only. Its function uses module-scope helpers and ql, so it would not lower under any option.
   • The director's E record measured zero jobs in cloud, hotcrm and objectui.

The question

The ruled lowering cannot run as written. Should it be withdrawn, so that a job body is authored as data, or kept by changing a public contract so the build can see the job's function?

Options

Business meaning:

• C: like a spreadsheet macro stored as text in the file, so it travels with the file. You write the macro text, not a pointer to code on your own machine.
• A / B: the platform tries to copy code from your machine into the file at save time. It only works when that code was written to run in the file's sandbox, and the common way to write it today is not.

四维分析

os-decision-facets

• ① 项目长远合理性： C 只留一种可移植写法——body 即数据,与 hook/动作的元数据形态一致,符合 ADR-0088「函数是代码、不是元数据」;A、B 都要让同一个函数同时满足进程内 JobHandlerContext 与沙箱 ctx 两种上下文,这是结构性陷阱,守卫只能拒绝、不能修复。
• ② 实际业务拉动： 零——四仓只有 examples/app-showcase 声明 job,且其函数用模块作用域辅助函数与 ql,任何方案都转不了;自动转换没有一个可被它服务的实测作者。
• ③ 防 AI 犯错： C 下严格 schema(仅 L2、超时一处、二选一必填)就是全部契约,写错在解析时响亮拒收;A、B 引入构建期代作者生成的 body 与一条拒绝路径,AI 要理解「何种函数可被转换」,出错面更大。
• ④ 创业阶段不扩散： C 什么都不加;A 改动流程函数契约(无拉动),B 新增一种已弃用键的写法外加运行时绑定改动,是三者中最宽的。

Prior rulings read: job body,job handler,lowercallables,build lowering,inline handler,sandboxed body → 0 hits; none; thread: 1 ruling(s) (5964305303); repo: objectstack-ai/objectstack

推荐：C。 终态句:两年后,应用包里任何服务端代码(hook、动作、定时任务)都是作者写下的沙箱代码体数据,任何安装门都能跑;构建不替作者从本机代码里「抠」出代码体。只看①选 C;②③④ 是否翻转:否(②零拉动、③响亮拒收、④零新增,均同向)。回退: A,且须等 #21489 先决定进程内 job 处理函数是否获得 ctx.api / ctx.log,否则 A 转出的代码体与进程内函数仍是两套上下文。置信缺口: 前提 2 由 dev 的管线测试在 781609d2f7 实测,本席未独立复跑;仓外(cloud、hotcrm)无 job,由 E 裁决记录实测,本席未重测。

After the ruling

• C: this card closes completed, citing the ruling. spec(system): JobSchema gains a sandboxed body, like hooks and script actions, so a job handler is declarable code that travels with a package (ruled on #21489, E) #21515 closes when PR spec(system): JobSchema gains a sandboxed L2 body and deprecates handler; a body job has one time limit #21538 lands, with its scope reading "build lowering withdrawn". The jobs docs already teach the data form. The dev's reverted lowering stays in history only.
• A: a domain:spec card for the functions contract change (identity-preserving check, its own contract review), then a domain:cli card for the guarded job lowering. Both are ordered after [Decision] install-local: a package's declared jobs are never scheduled — refuse the install, name them in the install answer, or make job handlers declarable bodies (the jobs half of #21322) #21489 decides the in-process job handler context.
• B: a domain:spec card for the inline job handler form, plus binding work folded into [Decision] install-local: a package's declared jobs are never scheduled — refuse the install, name them in the install answer, or make job handlers declarable bodies (the jobs half of #21322) #21489's runtime half.

Related

Ruling E 5964305303 · #21515 · PR #21538 · the dev report 5965564062 · #21489 (the runtime binder, domain:cli) · ADR-0088 · automation/flow-function.zod.ts.

Dedupe: the 100 most recently updated open issues here were listed by REST and grepped for job body, lowerCallables and job handler with lower: the only hits are #21515, PR #21538 and #21489, the source. No card asks this question.

Generated by Claude Code