Merge remote-tracking branch 'origin/main' into claude/issue-5265-save-receipt-truthful-wording

Author: claude

.changeset/injected-system-columns-author-time.md

@@ -0,0 +1,44 @@
+---
+"@objectstack/spec": minor
+"@objectstack/objectql": patch
+"@objectstack/lint": patch
+---
+
+fix(lint,spec,objectql): 编写期表达式与 `highlightFields` 校验识别注册表注入的系统列 (#5378)
+
+平台在每个业务对象上注入 `owner_id` / `created_at` / `organization_id` 等系统列,
+文档也把 `ownership: 'user'` 写作 "injects reassignable owner_id"。但编写期的两处
+校验只读**作者声明的** `fields`,于是注入列一律当作不存在:
+
+- `validate-expressions.ts` 的 `buildFieldIndex` 让 `has(record.owner_id)` 直接
+  报错 `unknown field owner_id`;
+- `highlightFields` 存在性检查对 `['owner_id']` 发出 "is not a field on this
+  object — it is silently skipped by every consumer"。
+
+也就是平台自己的 linter 否认平台自己的契约。结果是应用被迫**重声明系统列**才能通过
+编写期校验:hotcrm#548 为此在全部 12 个业务对象上显式声明了 `owner_id`(6 个对象曾
+报 `highlightFields` 警告,`contact_welcome` 触发器的 `has(record.owner_id)` 被硬
+拒)。这正是本项目视为缺陷的形状:能力已声明(列确实注入且有文档),但执行层不认。
+
+**权威来源只有一份。** 新增纯派生 `resolveInjectedSystemColumns()`
+(`@objectstack/spec/data`)回答"这个对象带哪些系统列",并由 registry 的
+`applySystemFields()` **消费**它——沿用 #3786 为审计字段族确立的分工:spec 声明
+**有哪些**列,registry 拥有**每列长什么样**。lint 通过同一派生取答案,因此编写期
+判断与运行时注入不可能不一致(`@objectstack/lint` 的包契约是"只依赖 spec,绝不依赖
+运行时",此前它根本无法读到权威)。两个消费面共用同一判定,不各写一份。
+
+**并入是按对象有条件的**,不是无条件放行整张系统列名单:`ownership: 'org' | 'none'`
+的对象没有 `owner_id`,那里的 `record.owner_id` 仍然是真错误并继续报;
+`tenancy.enabled: false` 无 `organization_id`;`systemFields: { audit: false }` 无
+审计四列;`systemFields: false` / `managedBy: 'better-auth'` 什么都不注入(只剩驱动
+提供的主键 `id`)。真正拼错的字段照旧被拒,并且注入列现在也进入 "did you mean?" 候选
+(`record.ownerid` → 提示 `owner_id`)。
+
+被解析的注入列在诊断与补全语义上与授权字段等同;类型健全性与 null-guard 两个索引
+**刻意**仍只读声明字段,原因写在各自注释里:列的 `type` 与可空性属于 registry 的列
+定义,在 lint 侧另立一份就是本次要消灭的第二份副本,而 null-guard 喂的是会中断构建的
+判定,擅自并入会让今天能构建的 stack 变红。
+
+注入行为本身零改动:`applySystemFields` 的输出在全条件矩阵上逐列不变(新增 parity
+pin 用实跑注入代码比对)。已显式重声明系统列的应用不受影响——重声明仍然合法,
+examples 三个 app 的 `os validate` 输出改动前后完全一致。

.changeset/objectql-retire-formula-now-snapshot-param.md

@@ -0,0 +1,36 @@
+---
+"@objectstack/objectql": patch
+---
+
+chore(objectql): retire `applyFormulaPlan`'s zero-caller `nowSnapshot` parameter and narrow its docstring to what actually holds (#5699)
+
+`applyFormulaPlan` declared a fourth optional parameter `nowSnapshot?: Date`
+whose only effect was `nowSnapshot ?? new Date()`. Not one of its three call
+sites ever passed it — `find`, `findOne`, and the write-response hydration
+`hydrateWriteFormulas` added by #5504 — so the parameter went down the
+`new Date()` branch from birth. Dormant code, removed rather than archived: a
+parameter that looks live is worse than no parameter, because everyone
+reasoning from it concludes the caller can pin the instant, and one caller
+plainly should have.
+
+No behaviour change (the removed branch was unreachable), no public API change
+(`applyFormulaPlan` is module-private and never exported).
+
+The docstring claimed the eval context "mirrors `applyFieldDefaults`". Half of
+that was true — the same keys, so `formula` and `defaultValue` expressions share
+one vocabulary — and half was not: the two pin their own `now`.
+`applyFieldDefaults` is handed the insert's pre-write snapshot, while
+`applyFormulaPlan` reads the clock once per call, because a formula is evaluated
+when a record is materialized. So inside one `insert` a `NOW()` default and a
+`now()` formula observe two instants a driver round-trip apart (sub-millisecond
+in practice; across a second/day boundary they can land on different calendar
+days). The docstring now says so, and names #5699 as where making them share one
+instant would have to be argued — it would hand the write path a determinism
+guarantee the read path cannot have, which is a semantic decision, not a cleanup.
+
+Adds the pins that the retired parameter's *appearance* was standing in for
+(`engine-write-formula-hydration.test.ts`): one snapshot per call shared by every
+row × every formula field, asserted by object identity on the eval context so a
+per-evaluation `new Date()` fails even when the milliseconds agree, on the write
+path and the read path alike; plus a tripwire that the default's instant and the
+formula's instant stay independently sourced.

.changeset/retired-keys-exact-registry.md

@@ -0,0 +1,44 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): 退休登记按**确切 key** 判定 —— 无关簇的同名叶子不再让 tombstone 冒充「已登记」(#4659)
+
+`scripts/build-schemas.ts` 的检查 (b)(`check:authorable-surface`)保证一件事:
+一个 authorable key 从 live 翻成 retired(`retiredKey()` 墓碑)时,这次退休必须
+被登记下来,否则 `spec-changes.json`(ADR-0087 D4)、生成的升级指南、`spec_changes`
+MCP 工具全是空的,消费者只能靠失败才知道。
+
+它此前是这样判定「已登记」的:取 key 的**叶名**,拿去和**全部 major** 的所有
+conversion / migration `surface` 子句做 `endsWith('.' + name)` —— 完全不看 key
+属于哪个 def。于是任何一条无关登记,只要 surface 以同名叶子结尾,就把这个墓碑判为
+「已登记」:
+
+- #4658 实测:`automation/Event:type` 被 tombstone、零 conversion,门禁全绿 ——
+  命中的是 protocol 11 的 `flow-node-http-callout-rename`(`flow.node.type`),
+  一个 flow 节点的 `type`,和状态机事件毫无关系。
+- #5509(ADR-0087 D2 `page-header-subtitle-alias`)登记
+  `page.component.page-header.description` 之后,任何叶名为 `description` 的 key
+  也进了同一个免检名单。`type` / `name` / `config` / `filter` / `schema` /
+  `description` 都是 authorable 形状上最常见的叶子,这条保证对它们整体失效。
+
+现在登记有了自己的表:
+
+- **新增导出 `RETIRED_KEYS_BY_MAJOR`**(`@objectstack/spec`,
+  `src/migrations/registry.ts`),值就是确切的 `` `${defKey}:${name}` `` 字符串 ——
+  `authorable-surface.json` 怎么写它就怎么写,去掉 `[RETIRED]` 标记。
+- 检查 (b) 改为对这张表做**精确集合判定**:不再有 `endsWith`,不再取叶名,不再从
+  相邻的 key 辐射过来。门禁失败时直接打印要粘贴的那一行和它该进哪个 major。
+- 新增检查 (b2):表里登记了一个**当前仍然 live** 的 key —— 一次没有任何东西消费的
+  登记 —— 直接失败;它会替一次尚未发生的退休提前放行。登记了一个本次构建**已不再
+  产出**的 key 则不是错误:墓碑满 ~2 个 major 之后由检查 (c) 放行其基线行,登记条目
+  留下,这是预期稳态。
+
+conversion 的 `surface` 保持散文形态、一个字没动:它面向作者、按作者书写元数据的
+形状表达(`flow.nodes[].outputSchema`),本来就无法可判定地映射回 def key。所以
+搬走的是机器事实,不是散文。一次退休仍然两样都要写:登记条目是**声明的凭据**,
+conversion 是**消费者照着做的处方**。
+
+不回填历史:检查 (b) 只在相对已提交基线的 live → retired **新**跃迁上触发,而更早的
+墓碑在基线里已经是 `[RETIRED]`,不会再触发它。所以这张表读作「在确切-key 门禁下登记的
+退休」,不是「历史上的全部退休」—— 空表在 `main` 上实测全绿。

.claude/agents/os-dev.md

@@ -168,6 +168,20 @@ Definition of done, in order:
   colour as information rather than as your verdict — every run after the label
   is exempt. Declaring the label in the PR body is not applying it: #5533 and
   #5538 each said so in prose and each still cost a PM hand-fix.
+- **Wait for CI to converge before you return the report — local green is not CI
+  green.** Read the gate jobs' real conclusions on the PR (**ESLint** and
+  **TypeScript Type Check**): this repo's family gates
+  (`check:engine-double-contract`, `check:error-code-casing`,
+  `check:route-envelope`, …) run *inside* the ESLint job, so one of them going red
+  shows up there and nowhere in your local `pnpm test` output. A job still
+  `in_progress` is not a pass, and the aggregate status is not the job's
+  conclusion. #5584 reported on local green while its ESLint job had no
+  conclusion yet; the job went red, the PR merged red anyway, and that red then
+  rode main's merge ref into every later PR's ESLint job until #5615 hot-fixed it.
+  A gate that goes red here is yours to fix in this task, not to report as done.
+  This wait is **foreground polling** — the same legitimate blocking wait as
+  `flock` in resource rule 1, and ⛔ never a background watcher you return from
+  mid-task (resource rule 6 still binds).
 - Tear down anything you started (dev servers on random ports).
 
 **Reverse verification — decide the expected direction BEFORE you run it.**

.claude/skills/pm-dispatch/SKILL.md

@@ -107,7 +107,7 @@ protocol is identical.)
 
 ## Operational notes(实测坑位)
 
-队列与平台层的九条实测结论。共同点:**判据取命令的输出,不取 API 字段的字面值,
+队列与平台层的十二条实测结论。共同点:**判据取命令的输出,不取 API 字段的字面值,
 也不取本地工作树的现状,更不取「看起来相邻」的两行日志** —— 每一条都是在这一步上
 咬过人之后写下来的。
 
@@ -242,6 +242,69 @@ draft、解绑 `Fixes`,免得一个错结论继续被当作已立案的事实引
 8 条讲过它的覆盖面)—— 两条 **issue** 描述同一个问题,没有任何门禁能看见,
 查重只能发生在立单前、你自己手里。
 
+**10. 合并前认门禁 job 的结论,不认聚合读数 —— advisory 门禁红着合并会毒化全仓。**
+PR #5584 的新测试文件触发 `check:engine-double-contract`(这一族门禁挂在 **ESLint
+job** 里),该 job 19:53Z 结论 `failure`,而 PR 在红了 **19 分钟后照常过队合并**。
+合并后,`main` 上这条红被 merge ref 带进**每一个后续 PR 的 ESLint job**,#5601 等
+直接中招;热修 #5615 才解除,治理侧另立 #5617。两句纪律:
+
+- 合并前必须确认**承载门禁族的 job**(本仓即 ESLint、TypeScript Type Check ——
+  `check:engine-double-contract` / `check:error-code-casing` /
+  `check:route-envelope` 等都跑在 ESLint job 内)已达 **`completed: success`**,
+  而不是「暂时还没出现 failure」。step 7 的 ACCEPT 那句 *once every check on the PR
+  is green* 要读成「每个门禁 job 的**结论**已出且为 success」,`in_progress`
+  不算数。
+- 「队列会把关」只对 **required** 检查成立。一条不在 required 集里的 advisory
+  门禁,merge queue 的 merge_group 检查集同样看不见它 —— 它红着合并进 main 就是
+  **共享损伤**,**任何车道发现都要立即止血 + 立单**(#5615 止血 / #5617 治理即
+  此形)。#5617 是本条的治理半边(required 集怎么配),与本条互补:配置面归它,
+  流程面归这里,两边都到位才关掉这个失效面。
+
+**11. dev 子代理自己死了 ≠ 维护者中止 —— 不得据推断立一道谁也不敢退的门。** #5085 的
+dev 子代理零推送、零分支就没了(子代理正常的 `/compact`/中断死法,step 6 的探活与
+step 5「Handing off an interrupted dev」讲的就是它)。前任 PM 把它**推断**成
+「维护者手动中止」,设了「是否重派等维护者示意」的门:该门从 08-05 07:00Z 立到
+08-06 02:42Z 解除,**近 20 小时**压着一个 p0-邻近的真 bug,直到维护者本人确认
+「没有中止」才发现是误判。两句纪律:
+
+- 子代理消失(零推送 / 零分支 / 无报告)是**子代理的正常死法**,按 step 4 的
+  **stale-claim reclaim** 处理(先探活 / SendMessage 复活,复活不成再回收重派),
+  ⛔ 不得推断为维护者意图。
+- 「维护者中止」只在有**显式信号**的记录时才成立 —— 维护者原话,或宿主明确回报
+  的 *stopped by the user*。同一条 #5085 上两种都出过:08-05 07:00Z 那次是推断
+  (误判,门压近 20 小时),08-06 04:12Z 那次是宿主信号(真中止,维护者两分钟后
+  示意重派、门即解除)。**判据是信号,不是症状**:两次的症状(零推送、无分支)
+  完全一样。没有显式信号就当死认领回收,⛔ 不要立一道没有重启条件的门 —— 那次
+  的门只写在「认领解除」评论里、标签退回了 `pm:queue`,于是队列视图显示可派发而
+  谁也不敢派,比 `pm:on-hold` 更隐蔽(状态机根本读不到它)。真需要 hold 就照
+  状态模型办:`pm:on-hold` + 带**重启条件**的评论成对落地(「A hold without a
+  restart condition is a state nobody can ever legally exit」)。
+
+**12. 判「正文被 sanitizer 截断」必须双读取 —— 单一读法的尾部缺失先算读取端截断。**
+#5148 / #5149(2026-08-05,分诊座位)与 #5164(cli 车道 PM)被判为「正文已被 GitHub
+sanitizer 截断,不可分诊/派发」,据此挂起并要求原作者重贴。事后以两种读法复核 ——
+REST 取 `body`(原文 4321 / 5183 / 4181 字符)+ 取 `body_html`(渲染版)—— **三条
+正文都完整**,`<object>` / `<id>` 一类占位符全部落在行内代码或围栏内、未被吞。
+三条判读均不成立,真因是**读取端(工具输出)截断**被误读成 issue 端截断;代价是
+三条 issue 各白停摆 1–2 天(#5148 是有脚本化复现的可入队缺陷,#5149 / #5164 是
+应当尽早进维护者决策箱的裁决卡),外加三张打给作者的假工单。两句纪律:
+
+- 判截断前必须**双读取**,`body_html` 要带 full 媒体类型才拿得到:
+
+  ```bash
+  curl -s "https://api.github.com/repos/<owner>/<repo>/issues/<n>" \
+    -H 'Accept: application/vnd.github.full+json'   # .body 原文 + .body_html 渲染版
+  ```
+
+  **两者在同一处断掉**才算 issue 端截断;任何单一读法的尾部缺失都先假定是读取端
+  截断(工具输出上限、分页、`[:N]` 切片)。这与 notes 6「零命中必须用一个确定存在
+  的邻近词反查」是同一条纪律的另一半 —— **缺失类读数在下结论前都要先证伪「扫描器
+  坏了」这个解释**。
+- step 0 的 **Repair first** 是**停摆指令**,成本由作者承担,所以它的判据必须比
+  其它分类更硬:误判一次的代价是一条可入队缺陷躺一天,外加一条打给作者的假工单。
+  已发出的重贴指令若事后证伪,**要在同一处公开作废**(同 notes 7:诊断结论一旦
+  公开发出又被推翻,更正要发在同样公开的位置)。
+
 ## Multi-repo coordination (backend / frontend / cloud)
 
 The product spans three repos with a fixed dependency direction:
@@ -1129,7 +1192,7 @@ attached.
 下面的停摆纠偏处理「带任务中状态的通知到了」;这一条处理更隐蔽的另一半:
 **通知根本不来**。宿主进程重启会把运行中的 subagent 连同其完成通知一起
 静默杀掉 —— 2026-08-05 实测,五个「在飞」dev 里三个(#5050/#5515/#5483)
-已死数小时,批次视图仍显示 5/5,实际吞吐 2/5,零信号。规程三条:
+已死数小时,批次视图仍显示 5/5,实际吞吐 2/5,零信号。规程五条:
 
 - 每次巡检(定时器唤醒、轮间隙)对**每个已派发且尚无远程分支/PR** 的
   dev 发一次状态询问(SendMessage,措辞「回一段简报后继续干活」,不改变
@@ -1140,6 +1203,17 @@ attached.
   优先用它;resume 不可用时才走接手协议。
 - 判据永远取正向证据(远程分支、PR、报告、探活回包),⛔ 绝不把「还没
   收到失败通知」读作「还在跑」。
+- **定时器重挂是每次巡检的第一动作,不是最后一个**(维护者 2026-08-06
+  授权)。巡检执行到一半被打断(穿插提问、事件风暴、会话中断)时,排在
+  末尾的重挂会整个丢失,守夜链就此断裂 —— 2026-08-06 实测:一次漏挂让
+  四连灭批静默了 ~100 分钟而不是探活门槛设计的 ≤45 分钟。先挂后查,链条
+  对中断免疫;挂错了间隔可以在本轮末尾用 delete_trigger + 重挂修正,但
+  「没挂」无法被本轮以外的任何机制补救。
+- **批量在飞期间,主巡检间隔不得长于 45 分钟**(同一授权)。探活门槛是
+  45 分钟,巡检间隔一旦超过它,门槛就成了写在纸上的数字 —— 最坏情形下
+  一个派发后即死的 agent 要等到下一轮巡检才被发现,静默窗口 = 巡检间隔,
+  而非门槛值。在飞清零的待命期可放宽到 60-70 分钟;有任何 dev 在飞即收紧
+  回 ≤45,灭批频发期(如宿主重启风暴)进一步压到 20-30 分钟。
 
 **A stalled subagent is this half's most common failure, and it never
 self-heals.** When a dev stops mid-task reasoning that "a background watcher will
@@ -1206,6 +1280,12 @@ against the report's own claims:
   plainly unrelated to the issue.
 - Test evidence in the report shows the actual commands and passing output,
   not a bare "tests pass".
+- **报告到达 ≠ CI 收敛。** arm auto-merge / 入队前**亲核门禁 job 的结论** —— 不止
+  `pull_request_read get_status` 那个聚合读数,要看 ESLint 与 TypeScript Type Check
+  这两个具体 job 的 `conclusion` 已为 `success`(门禁族都跑在它们里面,Operational
+  notes 10)。dev 可能在自己的 ESLint 还没出结论时就交了「本地绿」的报告 ——
+  #5584 的 advisory 红就是这样漏过复核、红着合并进 main 的;os-dev 定义侧已要求
+  「PR 开出后等 CI 收敛再交报告」,本条是它在复核侧的对账。
 - The diff plausibly satisfies the issue's acceptance criteria.
 - **收益穿过它必经的那道边界之后还在吗?** 判据(不是每单都做):这批工作的价值主张
   是否**依赖某个下游组件如实转发** —— HTTP 错误信封、序列化、日志汇聚、跨进程传输。