docs(spec,approvals): ApprovalEscalation.timeoutHours names its clock — calendar (wall-clock) hours

[os-zhuang]

Part of #13801

Clause-②: no — describe-only. No key is added, renamed or defaulted differently; the authorable surface and the JSON-schema manifest are unchanged; only the contract text of an existing key moves.

Ruling implemented (quoted)

From the domain:spec seat's ruling on the phase-1 measurement (issue 13801, comment 5506987580, 2026-09-02):

Mechanism ruled in-seat: B — consumption-side convergence, zero contract change. Clause-②: no.

B puts the clock where this platform already single-sources contract text — the Zod describe that gen:schema emits to json-schema/ and build-docs emits to the reference page — pins the one runtime site that computes the deadline, and teaches the rule where the next AI-authored hook is written. The lint leg is measured empty […] and is dropped, not deferred.

The maintainer's ruling of record behind it (2026-08-31, decision batch #18, verbatim 「其他同意」 on the split of the business-hours question): the A-half is that "this number is wall-clock hours" must be part of the declaration, not ambient prose. ⛔ Nothing here grows toward a business-hours calendar; ⛔ no clock key, because a key with a single legal value would be declared-but-inert (ADR-0049).

The four items

1. packages/spec/src/automation/approval.zod.ts:624-633 — timeoutHours gains a JSDoc (:624-632) and its describe (:633) now reads: Calendar (wall-clock) hours before escalation triggers — nights, weekends and holidays count. The platform ships no business-hours calendar: a request opened at 17:00 on a Friday with timeoutHours 4 escalates at 21:00 that same Friday. That string is the JSON-schema description and the reference-page cell; pnpm --filter @objectstack/spec check:generated --fix regenerated content/docs/references/automation/approval.mdx:41,105 and nothing else (authorable-surface anchor, api-surface, spec-changes all current). check:doc-authoring rule 3 (no tracker ids in customer-facing text): green. minApprovals in the same file belongs to the sibling PR for spec: ApprovalNodeConfigSchema.minApprovals describes "Default 1", but the quorum runtime defaults to ALL resolvable approvers #13809 and is untouched.
2. packages/plugins/plugin-approvals/src/approval-service.ts:610-624 — JSDoc above slaDueAt (the one runtime site that turns the declared number into a deadline) names the clock; no logic change (15 lines added, 1 removed, all comment). New packages/plugins/plugin-approvals/src/approval-service-sla-calendar-clock.test.ts (208 lines, 5 tests) pins the arithmetic through the real path openNodeRequest → getRequest → runEscalations with an injected clock: Friday 2026-01-16 17:00Z + timeoutHours: 4 → Friday 21:00Z, not escalated at 20:59:59.999Z, escalated at 21:00:00.000Z (before Monday's first working hour); a 168-hour deadline lands the next Friday at the same hour with Saturday and Sunday inside the window and no escalation on Monday 09:00Z; two DST cases (America/New_York spring-forward 2026-03-08 and fall-back 2026-11-01) show four elapsed hours regardless of what the local wall reads. Timezone assumption, stated in the file header: none is required — every instant is an ISO-8601 UTC string and the arithmetic is elapsed milliseconds, so the assertions hold under any TZ; the DST comments document the local-time reading. The engine double declares find + insert only (no update/delete member, so nothing for check:engine-double-contract to pin) and honours the caller's limit by presence (check:objectql-double-limit).
3. content/docs/automation/approvals.mdx:633-636 — one sentence in "Timeouts and escalation".
4. .changeset/approval-escalation-calendar-clock.md — @objectstack/spec patch (published contract text). No changeset for @objectstack/plugin-approvals: comment + test only.

Mechanical companion: content/docs/permissions/system-context.mdx is re-anchored by node scripts/check-system-context-census.mjs --fix (the JSDoc in item 2 shifted every later context.isSystem anchor in approval-service.ts; re-done from the merged tree after merging origin/main, as the os-regen pre-commit hook required).

Declared cross-domain limb

packages/plugins/plugin-approvals is a domain:services package. This PR touches it with a JSDoc and a new test file only — no runtime logic changes — as the ruling's "pin the one runtime site" leg; the services seat is named on the claim amendment for #13801.

Not in this PR (the other two limbs, both open)

• Skill teaching (+4 lines, skills lane): skills: teach the wall-clock rule where the next hours table is written — one clause on the approval escalation row, a hook-deadline rule in the data-hooks reference (+4 lines; skill limb of objectstack#13801, mechanism B) #14483 remains open — skills/** is a governed surface and is not touched here.
• The reference app's four prose sites (hotcrm): hotcrm: carry the wall-clock unit of the case SLA matrix in identifiers and one test, collapse the four prose warnings to one (app half of objectstack#13801, mechanism B) #14482 remains open — nothing in hotcrm is touched here.

Gates — derived union on the final head

git rev-parse --short HEAD = fb5c8a4a3 (branch merged with origin/main at 9c7d9d4b3 via scripts/pm/os-regen-merge.sh; the census page regenerated afterwards as its own commit). Union derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack on that head (74 commands; stderr line: "gate list derived from the tree of 'objectstack-ai/objectstack' at commit fb5c8a4"), each exit captured to a file before any pipe.

Must-haves, under scripts/pm/os-verify-lock.sh (VERDICT lines command-exit 0):

• pnpm --filter @objectstack/spec typecheck — exit 0 (check:test-typecheck: OK — 54 file(s) / 262 error(s) / 146 pinned signature(s)), sha fb5c8a4.
• pnpm --filter @objectstack/plugin-approvals typecheck — exit 0 (check:test-typecheck: OK — 8 file(s) / 324 error(s) / 27 pinned signature(s); tsc -p tsconfig.test.json --listFiles lists the new test file, so the test-typecheck leg measured it), sha fb5c8a4.
• pnpm --filter @objectstack/plugin-approvals exec vitest run --maxWorkers=2 src/approval-service-sla-calendar-clock.test.ts src/approval-service.test.ts — Test Files 2 passed (2) · Tests 303 passed (303), sha fb5c8a4.
• pnpm --filter @objectstack/spec check:generated — exit 0, 0 stale artifacts; pnpm check:doc-authoring — exit 0 (14496 customer-facing string(s) across 705 spec sources clean); pnpm check:nul-bytes — exit 0 (7922 tracked, no raw ASCII control bytes); node scripts/check-system-context-census.mjs — exit 0 (145 anchors resolve); pnpm check:objectql-double-limit — exit 0 (305 double(s) graded); pnpm check:quick-reference-counts — exit 0.

Union: 68 of 74 green on fb5c8a4. The other six exited with their own PREREQUISITE-NOT-MET / NOT-MEASURED text and are recorded as NOT MEASURED, not red (each names the unbuilt workspace or a missing CI log as its precondition; CI owns those runs): node scripts/check-dev-prereqs.mjs (exit 1, "45 of 67 workspace packages declare an entry point under dist/ that is not on disk"), node scripts/check-test-completeness.mjs (exit 3, needs a saved turbo run test log), pnpm --filter @objectstack/spec run check:skill-examples (exit 1, packages/client-react/dist not built), pnpm check:dual-build-cjs-loads (exit 3), pnpm check:i18n (exit 1, "Nothing was checked" — dist closure missing), pnpm check:type-check-debt (exit 3).

Two reds surfaced by a first pass on the pre-merge tree and fixed before the final head: check:objectql-double-limit (the new test's find double was limit-blind → applies the bound by presence) and check-system-context-census (line rot from the JSDoc → --fix). One declared caveat: the plugin-approvals readings ran against packages/objectql and packages/runtime dist built from pre-merge sources (the nine upstream commits touched their src; my rebuild filter mis-cut top-level package dirs and skipped them) — neither package is imported by the two suites run, and the CI build is the authoritative run.

Relay: sibling on the same file

After the merge at 9c7d9d4b3, origin/main advanced 14 more commits at PR time; none touched approval.zod.ts or its generated products (git log 9c7d9d4b3..origin/main -- packages/spec/src/automation/approval.zod.ts is empty; #13809 has not landed). The only watched path that moved is content/docs/permissions/system-context.mdx (953a81f, one anchor line), which the queue's pre-commit regen re-derives; a second resync was not chased so the branch stops moving.

Session: https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

🤖 Generated with Claude Code

https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

1 anchor(s) derived from 2 changed package(s); no hand-written page names any of them. ⚠️ 1 changed file(s) yielded no anchor (packages/plugins/plugin-approvals/src/approval-service.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/plugins/plugin-approvals/src/approval-service.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 128 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 9acddde94c5242db560913aa2d2c2e8f7b843511 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 92bab48cf484449e3567d6f1640e79795125000a — the merge of head fb5c8a4a3dad3363f9583f447ecc67a36fdebb6f into base 9acddde94c5242db560913aa2d2c2e8f7b843511, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 92bab48cf484449e3567d6f1640e79795125000a && git checkout 92bab48cf484449e3567d6f1640e79795125000a
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 9acddde94c5242db560913aa2d2c2e8f7b843511 fb5c8a4a3dad3363f9583f447ecc67a36fdebb6f && git checkout -B drift-repro 9acddde94c5242db560913aa2d2c2e8f7b843511 && git merge --no-ff fb5c8a4a3dad3363f9583f447ecc67a36fdebb6f

node scripts/docs-audit/affected-docs.mjs --json 9acddde94c5242db560913aa2d2c2e8f7b843511

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

[github-actions]

⛔ merge queue 构建失败 — 先分诊，再决定要不要重排

队列构建 33623906645 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集），
所以失败的测试可能在本 PR 没碰过的包里 —— 那不是重排能修的。每次盲目重排都会让排在后面的所有 PR 重建一轮。

失败的 job（日志抽取，best effort）：

• Test Core (1/6) — 失败步骤: Run this shard's tests

  @objectstack/cli:test:  FAIL   unit  test/vitest-tiers-partition.test.ts > the two tiers of packages/cli (#13504) > INTEGRATION_FILES equals the behavioural predicate over every file on disk
    ↳ 失败原因: @objectstack/cli:test: AssertionError: files that spawn the CLI or boot a kernel/driver but are NOT in INTEGRATION_FILES (add them): expected [ Array(1) ] to deeply equal []
  

↳ 失败原因 是判读的关键：超时（Test timed out in … / Hook timed out in …）多半是负载/时序，不是本 PR 的回归；
断言（AssertionError: …）才指向真实的行为改变。两者的 FAIL 行长得一模一样，只有这一行能区分。

⚠️ 断言这一侧有一类例外，判据是断言在测什么，不是它是不是 AssertionError。 断言的对象是产品行为（一个值、一个形状、一次拒收）⇒ 照上面读：真实的行为改变，去查，⛔ 不要重排掉；
断言的对象是这次实验自身的有效性前提（跑完的耗时、负载下的先后、任何只在时间预算内才成立的条件）⇒ 它跟超时是同一类，同样对负载敏感，重排一次是合法的判别手段。
识别是机械的：断言的消息或它比较的值本身点名了一段时长、一个时间戳、一个耗时计数。实测过的一对 —— AssertionError: SecurityPlugin.init() ran: expected false to be true 测的是产品行为（真回归）；
AssertionError: this run took over a second, so second-precision stamps could have differed too: expected 1006 to be less than 1000 测的是实验前提：它守护的那条不变式当时是绿的，同一个 head 原样重排一次即成功。
穿着 AssertionError 外衣的时间测量，仍然是时间测量。（⛔ 这只改「怎么读一次红」，不改「哪些测试可以重排」——后者由别处管。）

跨 PR 相同签名（24h，按失败测试文件聚合）：

• test/vitest-tiers-partition.test.ts — 24h 内已弹出 2 个互相独立的 PR（test(cli): split the suite into named unit and integration vitest tiers #14536、docs(spec,approvals): ApprovalEscalation.timeoutHours names its clock — calendar (wall-clock) hours #14542）。汇总 issue：Queue-flake anchor: test/vitest-tiers-partition.test.ts #14554（新建）
• ⚠️ 24h 评论账本没读完（超过 5 页仍未读到窗口尽头），所以上面的「不同 PR 数」是下界，不是全量。

历史信号：

• 本 PR 过去 24h 无队列失败记录（首次）。
• 过去 24h 队列共有 2 个失败构建（不含本次）。

分诊清单：

1. 失败测试在本 PR 改动的包里 → 真回归，修 PR。
2. 失败测试与本 PR 无关 → 看上面的「跨 PR 相同签名」；已有汇总 issue ⇒ flaky/环境问题实锤，去那张 issue 上谈，修好前重排只会再烧一轮全队列。
3. 两者都不是 → 可能与同组 PR 语义冲突；等前面的 PR 落地或失败出队后再重排一次即可，不要连续重排。

---

Generated by Claude Code · merge-queue-triage workflow (#4859)

[claude]

Queue build 33623906645 red — not this PR's; no change needed here. (domain:spec seat, session session_01GDA48PuRFrHyRfdkBz8m21.)

The failing check Test Core (1/6) fails packages/cli/test/vitest-tiers-partition.test.ts, a file this PR does not touch and that is not on main: it is introduced by PR #14536, which sat ahead of this PR in the old queue stack (ccfa9556) and was ejected on the same signature. Its INTEGRATION_FILES misses the #14505 guard test that constructs ObjectQL, so the assertion fires on any tree that contains #14536 — the reading is on the anchor #14554. This PR's file set (packages/spec, packages/plugins/plugin-approvals, content/docs, one changeset) is disjoint from packages/cli.

The queue has already rebuilt this PR on the post-ejection stack (queue head 1f456906 on b8a16be2, none of whose trees carry that test); that build is in progress and is the one that counts. No re-run requested, no push.

---

Generated by Claude Code