spec: JobHandler 增加可选的「跑完但没干成」回报通道 —— #5548 裁决(B-minimal)的契约半边,可加性,Promise<void> handler 零改动

[os-project-manager]

Part of #5548(维护者 2026-08-08 批复 services 座位三轴分析,采纳 B-minimal)。按 shared-contract 规则(packages/spec 恒归 spec 座位)contract-first 拆分:spec 半边先行,services 半边(#5548,DbJobAdapter 映射)Blocked-by 本单。

裁决要点(不再重开)

• A(让这类 handler 抛错)被否:改变 JobHandler/IJobService 失败语义,第三方实现可能据 throw 重试——wait 定时唤醒 job 在 resume 没能消费掉暂停时也会自我取消 —— store 短暂不可达即丢掉这一次唤醒,run 挂到下次重启才被捞回 #5529 当时已明确拒绝顺手这么做;
• C(文档化「status = 没抛异常」)被否:把审计面的静默合法化,违背「fail-open/fail-closed 都可裁,静默不可裁」($not 的语义在 driver-sql 与 driver-memory / formula 之间分叉：NULL 行的去留相反，$not: {} 一个是 TRUE 一个是 FALSE #5146/声明式 apis:(ApiEndpoint)入站面全链路零执行:元数据装载成功、路由从未挂载、matchEndpoint 全仓无实现 #4936/fix(objectql): 校验规则谓词求值失败时 fail closed,并把合并记录补全为声明形状 (#4649) #4761 一脉);
• B-minimal 采纳:给 handler 一个可选、可加的「跑完但没干成」回报方式;sys_job_run 得以表达第三态。

spec 侧要做的(API 形状由 spec 座位定夺)

packages/spec/src/contracts/job-service.ts 的 JobHandler(现返回 Promise<void>,只有 throw / 不 throw 两态)增加可选的 degraded-outcome 回报通道。候选形状(spec 座位择一或另断,以下仅供起点):

• handler 可选返回值:Promise<void | JobRunOutcome>,JobRunOutcome = { outcome: 'completed' | 'degraded'; reason?: string };
• 或 ctx 回调:ctx.reportOutcome({ degraded: true, reason })。

硬约束(裁决的可加性条款):existing Promise<void> handler 逐字节不动、语义不变;不回报 = 现状(没抛错 ⇒ success)。TSDoc 必须写明三态语义与「这不是失败,不触发重试」——第三方 IJobService 实现的兼容性是本单验收关键。

消费预告(services 半边,#5548,⛔ 不在本单实现)

DbJobAdapter.wrap() 把回报映射为区别于 success 的 sys_job_run.status(如 degraded),bumpJob 同步;首个真实消费者是 #5529 的 wait 唤醒 handler(STORE_UNAVAILABLE 打空那一枪)。Studio 作业界面读此面——枚举扩展的向后兼容按 spec 车道纪律处理。

佐证

#5548(实测:打空的唤醒在 sys_job_run 上与成功唤醒完全一样)、#5529(刻意不抛错的原始决定)、db-job-adapter.ts L161-176 / L277-299、job-service.ts(JobHandler 现契约)。

来源座位:services(会话 session_01USNUyHEr7uaU6MoEWXitei);domain:spec 归 spec 座位派发,本单不认领。