docs: v17 docs sweep run 5 — rc.2 catch-up

[os-zhuang]

Follow-up to #4877. With the rc.2 release page written, I swept the hand-written docs against the same window (2bafe62e..a2ebea2e) for pages still teaching something the window changed — the run-5 counterpart to the run-4 rc.1 catch-up.

The sweep came back mostly clean: activationEvents, app.homePageId, translation.validationMessages, the script-node actionType branches, managedBy: 'system-data', atomic / ROLLED_BACK / NOT_ATTEMPTED, findOne's throw-on-empty, the bulk_update / bulk_delete webhook pair and datasourceMapping-is-routing were all already updated by the PRs that changed them. Retired datasource blocks (retryPolicy / healthCheck / capabilities / readReplicas), findStream, openApi31 and the dual-source renames have no hand-written doc references at all. Three pages had drifted.

1. data-modeling/validation.mdx contradicted itself

The has(x) callout (added by #4763) says an unevaluable predicate is "rejected fail-closed". Twelve lines below it, the condition paragraph still said:

A predicate that cannot be evaluated (parse error, unbound variable) is treated as a broken rule — it is logged and skipped rather than blocking the write.

That is precisely the fail-open behaviour #4649 reversed, and it is the sentence an upgrading author reads to decide whether their rules are enforcing anything. Rewritten to the shipped contract: rejection with VALIDATION_FAILED naming the rule and the offending key, severity still governing blocking, and the total stored-⊕-payload record that makes the has() callout true in the first place.

2. automation/hooks.mdx had no coverage of the declarative condition gate

One passing clause under wildcard hooks, and nothing else — while three changes landed on it in this window, one of them breaking. Adds a "The condition gate" section:

• hook 的 condition 求不出值时:全局 fail loud —— 抛错并中断该次操作(方案 B 已拍板;Blocked-by #4770) #4775 — an unevaluable condition now ABORTS the operation instead of warning and skipping the hook. Written with the reason the two outcomes had to split: swallowed into a before* guard the old behaviour silently let writes through; swallowed into an audit hook it silently dropped records.
• bug(objectql): hook 条件对着「只含本次更新字段」的残缺 record 求值，取不到的字段被吞成 false —— 审计 hook 静默不触发 #4770 — the condition evaluates against stored ⊕ payload, total over declared fields, not the write's payload alone. Includes the concrete trap: condition: "record.done == true" did not fire on ordinary updates because done was not in the payload.
• bug(objectql/docs): hook condition 的 CEL 作用域只绑定 record —— 文档教的 previous.x / ctx.record 根本不存在,过渡型条件写不出来 #4784 — previous is bound, so a condition can express a transition; plus the upgrade note that record.x == v alone is now true on every update of an already-matching row.

3. concepts/metadata-lifecycle.mdx did not list job

This is the page that explains the two-tier overlay / runtime-create gate, so it is where an author looks when "create job" disappears from Studio. #4509 set both allowOrgOverride: false and allowRuntimeCreate: false on job. Adds the row with its reasoning (handler names a compiled-bundle function a runtime writer has no way to reach, so a runtime-created job saved and was never scheduled) and the still-supported doors. Also notes that the standalone validation kind is gone under ADR-0088, since the paragraph below the table already discusses which types do not exist.

Filed, not fixed

content/docs/ui/apps.mdx has zero coverage of AppSchema.areas[] — no mention of the word anywhere in the hand-written docs — despite three changes landing on it this window (#4667 order, #4651 the two fail-open area gates, #4722 server-side enforcement of item-level gates inside areas) and a load-bearing security asymmetry that now only exists in changesets and the spec's .describe strings: item-level requiredPermissions is server-enforced in both trees, while visible is client-only at every level. Writing that section is more than a sweep should invent, so it is #4880, cross-referenced with #4749 (which fixes the spec-side prescription wording for the same surface).

Verification

• node scripts/check-doc-authoring.mjs — 215 files clean
• node scripts/check-release-notes.mjs — OK
• ADR link targets checked against docs/adr/ filenames

Docs-only; releases nothing.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 3, 2026 12:56pm