Merge branch 'main' into claude/issue-6212-batch-c-frozen-face-types

Author: os-zhuang

.changeset/bulk-action-required-permissions.md

@@ -0,0 +1,36 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): `BulkActionDefSchema` accepts `requiredPermissions` — the capability gate the selection bar already enforces (#6257)
+
+The renderer has filtered selection-bar buttons on `def.requiredPermissions`
+since objectui#3492 (`BulkActionBar` runs the same `useCapabilityGate` as the
+row kebab and record header), but the `.strict()` `BulkActionDefSchema` did not
+declare the key, so no legal metadata could ever reach that filter —
+`enforced ≠ declarable`, the mirror image of the "declared ≠ enforced" gap.
+The forms with no workaround were the INLINE data-plane defs
+(`operation: 'update' | 'delete'`): they dispatch no action, so unlike a def
+promoted from `bulkActions: ['<name>']` (or an aggregate def naming a declared
+action) they have nothing to inherit a gate from. In practice that meant a
+declarative bulk delete — the button that most needs a gate — was visible to
+every caller who could open the list, and rejected only per record, server-side,
+after the click.
+
+`BulkActionDefSchema` now declares an optional `requiredPermissions: string[]`
+with `action.requiredPermissions` semantics verbatim: absent or empty always
+passes, several entries AND, a client that cannot resolve the caller's
+capabilities fails OPEN (the server stays the authority), and the platform-admin
+bit grants no exemption — the gate reads grants. On a data-plane def the key
+governs visibility only; the write is still authorized by the data API's object
+permissions and server hooks. The `ActionSchema` near-miss aliases
+(`permissions`, `capabilities`, `requiresPermissions`, `requiredCapabilities`,
+`acl`) rename onto the new key here too. No renderer change: objectui's
+`BulkActionDef` type and `BulkActionBar` filter shipped in objectui 11
+(objectui#3548).
+
+Specimens: `examples/app-showcase` `showcase_project.default` gains the two
+inline gated defs the #6157 action-gating matrix could not pin — `relabel_ops`
+(`update` + `patch`, gated on the Ops-held `showcase.export_data`) and
+`purge_restricted` (`delete`, gated on the granted-to-nobody
+`showcase.restricted_ops`).

.changeset/datasource-unbuilt-workspace-remedy.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/service-datasource": patch
+---
+
+fix(service-datasource): 未构建的工作区不再被当成「配置写错了」(#5794)
+
+datasource 的 fail-fast 报错原本只有一句收尾建议,不分成因:
+
+```
+✗ datasource 'default': connect failed — Cannot find module
+  '…/@objectstack/driver-sql/dist/index.mjs' imported from …
+  Fix the datasource configuration, or set OS_ALLOW_DRIVER_CONNECT_FAILURE=1
+  to boot anyway and serve errors until it is reachable.
+```
+
+对「数据库真连不上」——错的 DSN、轮换掉的密码、断掉的网络——这句话是对的。
+但对**驱动包没构建**这一个成因,两半都是有害建议:
+
+- **「Fix the datasource configuration」** 把读者支去改一份本来就正确的配置。
+  在那里写什么都变不出一个 `dist/` 目录。
+- **「set OS_ALLOW_DRIVER_CONNECT_FAILURE=1 to boot anyway」** 比没用更糟:
+  它不是绕过问题,而是**藏起**问题。半个工作区会宣称自己启动成功,然后对每个
+  请求回 `ERR_DATASOURCE_UNAVAILABLE`——比诚实地拒绝启动难查得多。那个开关是
+  为「数据库暂时不可达」准备的(一个关于世界的事实,可能自己好起来);缺构建产物
+  是关于这份 checkout 的事实,不该有任何环境变量能启动越过它。
+
+而唯一有效的修法(`pnpm build`)一个字都没提。
+
+现在 connect 失败会按**成因**选收尾句。底层错误是模块解析失败时(ESM `import()`
+报 `err.code === 'ERR_MODULE_NOT_FOUND'`,CJS `require()` 报 `MODULE_NOT_FOUND`;
+`code` 被 re-throw 丢掉时退回 `Cannot find module` / `Cannot find package` 文本),
+消息改成:
+
+```
+The driver package could not be LOADED at all — it is not installed, or its build
+output is missing. That is a build precondition, not a datasource fault: the
+configuration is fine, and no boot-time override can make a driver that does not
+exist answer a query. Run `pnpm install && pnpm build`, then start again.
+```
+
+一个正确修法,只说一次,**不提**那个逃生开关——连「别用它」都不提:一个已经卡住的
+读者会去找最短的那行看起来能让他继续的话。这与 `datasource-pool-support.ts`
+(#5714 / #5931)和 `check:dev-prereqs`(#5795)是同一条消息纪律。
+
+判据复用 `@objectstack/types` 的 `isModuleNotFoundError`(framework#3265 起的唯一
+所有者),不另起一份;它先看结构化的 `err.code`、再退回文本,而这个结构化信号原本
+在 `handleFailure` 只收 `reason: string` 时被丢弃了,所以抛出值本身现在也一并传入。
+
+**纯诊断分类,零行为变化。** fail-fast 的判定、触发时机、抛出的错误类型、保留的
+连接状态,以及设了 `OS_ALLOW_DRIVER_CONNECT_FAILURE` 时的降级启动路径全部不变;
+其它成因(真连接失败、驱动不受支持、凭据解析不出)的消息逐字未动。

.changeset/degraded-suspended-run-load-log-cause-meta.md

@@ -0,0 +1,40 @@
+---
+"@objectstack/service-automation": patch
+---
+
+fix(service-automation): 降级版挂起态读取器的「存储读不到」告警不再把驱动错误拼进 message,改走 meta (#6230)
+
+`engine.ts` 的 `loadSuspendedRun` —— `loadSuspendedRunStrict` 的**降级版**读取器 ——
+在 catch 里把**我们不控制文本**的数据源驱动失败原因直接插进了 `logger.warn` 的 message。
+`ObjectLogger.write()` 一次调用只加一个「时间戳 + 级别」记录头,message 里的换行会把
+**一条**记录变成多个物理行,后面几行既无级别也无时间戳。
+
+这条比 #5912(PR #6228)刚治完的那条**多一层危害**:`ObjectLogger` 把 `warn` 路由到
+**stdout**,而 `serve` 的 boot-quiet 窗口只包了 `process.stdout.write`,其
+`BootLogCapture.offer()` 仅在该物理行带级别头时才保留 —— 所以无头续行是被**直接丢弃**,
+不只是被误读。而它在 boot 期真实可达:`plugin.ts` 的 `start()` → `rearmSuspendedWaitTimers`
+→ 对 overdue 运行 `engine.resume()` → `resume()` 的授权 gate 走的正是这个降级版读取器。
+
+实测:一个三行的 better-sqlite3 驱动错误把这条告警切成 **3 个物理行**,过 boot 缓冲的
+过滤后**只剩 1 行**留下 —— 而留下的那一行恰恰不含任何驱动事实。
+
+改法与 #5048 / #5575 / #5636 / #5661 / #5737 / #5912 完全同一套,零新词汇:**message
+单行自足**,外来 cause 交给 `Logger` 契约(`packages/spec/src/contracts/logger.ts`)
+`warn(message, meta?)` 的**第二**参 —— 注意与 `error(message, error?, meta?)` 的第三参
+不同,`warn` 没有 `Error` 槽。
+
+对运维可见的变化(日志形状,非行为):
+
+- 这条记录恒为**一个**物理行,不论日志格式,boot-quiet 窗口内不再丢字节;
+- 原因文本从 `msg` 末尾的 `: <驱动文本>` 移到记录的 `error` 字段(`meta`),多行驱动
+  错误由 `JSON.stringify` 转义换行后完整保留 —— 一个字节都不丢;
+- message 补上了这条降级的**后果**:读失败被翻译成 `null`,调用方(resume gate、screen
+  取数)看到的与「本来就没有这个挂起运行」完全一样,而运行本身未被触碰、仍停在原处;
+  原文本只说了「读失败」,没说读失败被翻译成了什么。
+
+刻意**不变**的一处,已钉上回归测试:**级别仍是 `warn`**。这是一个刻意的**功能性**降级
+读取器(注释写明它服务于只需要 best-effort 答案的顺带读取方),真正需要区分「存储挂了」
+与「运行没了」的 `resumeInternal` 用的是严格版 —— 按 #4632 的判据这不是耐久性降级,
+上调到 `error` 才是该规则的镜像误用(整个故障期间每次 gate 查询都报警)。
+
+按记录末尾驱动文本字面量 grep 这条记录的日志查询,需要改成读记录的 `error` 字段。

.changeset/flow-function-lowered-declaration.md

@@ -0,0 +1,70 @@
+---
+"@objectstack/spec": minor
+---
+
+fix(spec): `functions: { fn: { handler, effect: 'writes' } }` survives `objectstack build` (#4976)
+
+`FlowFunctionEntrySchema` gains a fourth union member — the **lowered
+declaration**, a `functions` entry whose `handler` has been replaced by the
+string ref `objectstack build` emits:
+
+```
+functions: {
+  sweepProjectHealth: { handler: 'sweepProjectHealth', effect: 'writes' },
+}
+```
+
+Nothing an author writes changes. This shape is produced by the CLI, not typed
+by a person: `lowerCallables` replaces every inline callable with a serialisable
+ref before the stack is parsed (it must — `z.function()` wraps callables and
+would break the ref mapping), and since #4396 it keeps the declaration beside
+the ref so what a function said about itself survives into the artifact. The
+union was not extended in that change, so the artifact it started emitting was
+rejected by the very schema it had to pass:
+
+```
+  ✗ Validation failed
+
+  functions:
+    ✗ functions
+      invalid_union: Invalid input
+```
+
+Loading from source was unaffected — `objectstack dev`, `objectstack validate`
+and the test suite all passed — so the failure appeared only at build, on the
+one spelling the platform asks writers to use. That is the same asymmetry #4343
+fixed for the bare handler ref, one shape over.
+
+**Why this was worse than a failed build.** `effect: 'writes'` exists so a
+function that writes is not counted as having written nothing (#4396, #4354): a
+`script` step reports no record metrics *because* flow functions are
+contractually pure, and a declared writer instead reports `unmeasuredEffect` so
+the run's broken-sweep query (`selected > 0 AND acted = 0 AND unmeasured = 0`)
+stays off it. The error above names no key, no entry and no reason, so the
+practical repair an author reaches for is deleting the declaration — shipping an
+undeclared writer, which is exactly the state it exists to prevent, recorded
+permanently in `sys_automation_run`.
+
+**One behaviour change worth stating.** `{ handler: 'someName' }` written by
+hand now parses where it used to be rejected as "handler is not callable". The
+rejection could not survive this member and should not have: a bare string entry
+(`functions: { foo: 'foo' }`) has been accepted since #4343 with the caveat that
+it registers nothing, so refusing the record spelling of the same mistake while
+accepting the string spelling was two dialects for one contract. Both fail the
+same way, loudly, at execute: `no function named '…' is registered` (#1870).
+Everything else stays strict — the lowered member is *derived* from the authored
+declaration rather than re-typed beside it, so `{ handler: 'fn', efect: 'writes' }`
+still raises the named surface and the `` `efect` → `effect` `` prescription, an
+unknown `effect` value is still refused, and an empty ref is still not a name.
+
+**Runtime is unchanged and was already correct.** `normalizeFlowFunctionEntry`
+returns `undefined` for a lowered entry in both its shapes, because neither
+carries a callable; `mergeRuntimeModule` re-attaches the sidecar module's
+function to the declaration the JSON carried *before* any collector runs, so
+`effect` reaches `collectBundleFunctionEntries` intact on the built path.
+
+The two halves are now pinned against each other by a round-trip test that
+drives the real pipeline (`defineStack` → `normalizeStackInput` →
+`lowerCallables` → parse) instead of a hand-written sample of what the lowering
+is believed to emit — the crossing neither side previously made, which is why
+both stayed green while the build failed on the join.

.changeset/flownode-parses-its-regions.md

@@ -0,0 +1,57 @@
+---
+'@objectstack/spec': minor
+'@objectstack/service-automation': patch
+---
+
+feat(spec)!: `FlowNodeSchema` parses its own ADR-0031 regions — the post-parse pass retires (#4415)
+
+`FlowSchema.parse` normalized a flow's own `nodes[]` / `edges[]` but could not reach a
+**region**, because a region lives inside `FlowNodeSchema.config` — a deliberately open
+`z.record` (ADR-0018). #4381 closed the resulting gap with a **post-parse pass**,
+`normalizeControlFlowRegions`, that every caller had to remember to run:
+
+```ts
+const flowShell = FlowSchema.parse(converted);
+validateControlFlow(flowShell);
+const parsed = normalizeControlFlowRegions(flowShell);   // ← had to remember
+```
+
+That is an unwritten rule on top of a parse, and it is exactly the condition the #4347
+family of defects grows in: a new consumer — a Studio publish path, an MCP tool, a bulk
+validation script — takes a `FlowParsed` and uses it, holding a **half-parsed flow that
+looks finished**. Nested edge predicates were still bare strings, nested nodes had not been
+through `.strict()`, and nothing said so.
+
+Now the schema does it. `FlowNodeSchema` carries a `.transform()` that parses each declared
+region slot — `loop.config.body`, `parallel.config.branches[]`, `try_catch.config.try` /
+`.catch` — through the schema that slot's value *is*. Nesting needs no manual recursion: a
+region's `nodes` are `z.array(FlowNodeSchema)`, so Zod re-enters the transform on the way
+down. **"Parsed" now means parsed at every depth** (Prime Directive #1), from any entry
+point — including `FlowNodeSchema.parse(node)` on a single node, which the old whole-flow
+pass could not serve at all.
+
+## Migration
+
+**`normalizeControlFlowRegions` is removed from `@objectstack/spec/automation`.** Delete the
+call; the parse above it already did the work:
+
+```diff
+  const parsed = FlowSchema.parse(converted);
+  validateControlFlow(parsed);
+- const normalized = normalizeControlFlowRegions(parsed);
+```
+
+Its replacement, `parseFlowNodeRegions(node)`, is exported for the same purpose one node at
+a time, but you should not normally need it — it is the transform's own body.
+
+**`FlowNodeSchema` is now a `ZodPipe`, not a `ZodObject`,** so it no longer has `.shape` /
+`.extend()` / `.pick()`. `z.infer` / `z.input` / `.parse` / `.safeParse` and
+`z.toJSONSchema` are unaffected, and the authorable key set is byte-identical (verified by
+`check:authorable-surface`). If you were reaching for the object half, read it from the
+pipe's input side — `FlowNodeSchema.def.in` — which is also what the repo's own generators
+do (`pipeAuthorableSide` in `scripts/lib/zod-graph.ts`).
+
+One visible consequence in the generated reference: `content/docs/references/automation/flow.mdx`
+now renders FlowNode's **input** shape, so keys carrying a `.default()` (`boundaryConfig.interrupting`,
+`inputSchema[].required`) show as optional. That is what an author actually writes, which is
+what an authoring reference should say.

.changeset/hook-context-api-scoped-context.md

@@ -0,0 +1,48 @@
+---
+"@objectstack/spec": major
+---
+
+feat(spec)!: `HookContext.api` 从 `z.unknown()` 收窄为 `IScopedContext`，文档教的第一个 hook 终于编译得过 (#5945)
+
+`HookContext.api` 是文档教的**主数据通道**，而它的类型是 `unknown`。于是所有文档、技能、示例里那个标准写法：
+
+```ts
+handler: async (ctx: HookContext) => {
+  const users = ctx.api.object('user');   // error TS18046: 'ctx.api' is of type 'unknown'.
+}
+```
+
+一行都编译不过 —— 包括 `hook.zod.ts` 里 `api` 这个键**自己 JSDoc 上的示例**。语料库全在这么教（`skills/objectstack-data/references/data-hooks.md`、`content/docs/automation/hooks.mdx`、`content/docs/api/error-handling-server.mdx`、`content/docs/kernel/runtime-services/*`），这些块都没进 `os:check`，所以从来没有一道门看见过。唯一进了 `os:check` 的那块（`runtime-services/examples.mdx`）也只能靠在示例里自建一个 `type CrossObjectApi = …` 再 `ctx.api as CrossObjectApi` 才编得过 —— 每个消费方各 cast 一遍、cast 的形状无人校验，正是 contract-first 要终结的方向。
+
+**本次落地维护者裁决 C**：`packages/spec/src/contracts/` 新增 `IScopedContext` / `IScopedObjectRepository`（与 `IDataEngine` / `IObjectQLEngine` 同层同风格），`HookContext.api` 的 TS 类型指向它。
+
+**声明面 = 语料库实测的调用点**，不多也不少（证据表在 PR 正文，逐条 file:line）：
+
+- `IScopedContext`：`object(name)` + `transaction(cb, opts?)`
+- `IScopedObjectRepository`：`find` / `findOne` / `count` / `insert` / `update` / `updateById`
+
+`upsert` / `delete` / `aggregate` / `create` 只出现在文档的**方法表与能力表**里、从没有一处调用点（表格不过编译器），`sudo()` 的三个调用方全部把值持成 `any` 且它是提权动作 —— 一律不声明，等到有调用点再按同一条规则加。这与 `IDataEngine` 当年（#4251）确立的「有证据才声明」是同一条纪律。
+
+**运行时零变化**：Zod 侧仍是 `z.unknown()`（`z.custom` 会让 `HookContext` 在 JSON Schema 里不可表达，`gen:schema` 直接不再产出 `json-schema/data/HookContext.json`，进而在下次 `gen:docs` 抹掉它的参考页 —— 实测过，不是推测）。收窄是纯静态的：接受的值、JSON Schema、生成的参考页行全部逐字节不变，只有 `.describe()` 文案改了。
+
+**漂移由编译器盯着**：`packages/objectql` 的 `ScopedContext` / `ObjectRepository` 声明了 `implements`，契约与引擎实际绑定的那个对象再也不能各说各话（把 `updateById` 改个名，objectql 的 `tsc` 会在 `implements` 处和五个 hook 派发点同时报错 —— 实测过）。
+
+**FROM → TO —— 什么代码需要改**
+
+读取端只会变宽，原来编译得过的读法一行都不用动（原来根本没有能编译过的读法）。两类**写入端**可能要改：
+
+```ts
+// 1. 自建 cast 的消费方 —— 删掉 cast 即可，`ctx.api` 现在自带类型
+-const api = ctx.api as CrossObjectApi;
+-const account = await api.object('crm_account').findOne({ where: { id } });
++const account = await ctx.api?.object('crm_account').findOne({ where: { id } });
+
+// 2. 构造 HookContext 字面量的测试替身 —— `api` 现在必须是 IScopedContext 形状（或省略）
+ const ctx: HookContext = {
+   object: 'account', event: 'beforeInsert', input: {}, ql: {},
+-  api: whateverStub,
++  api: undefined,   // 或一个带 object(name) / transaction(cb) 的替身
+ };
+```
+
+`api` **仍是可选的**：`buildHookApi` 在全部五个派发点都会设置它，但改成必填会开始拒绝今天能过的部分上下文（没有活引擎时构造的 context），所以读法是 `ctx.api?.object(…)`。

.changeset/hook-ctx-doc-alias-reads-removed.md

@@ -0,0 +1,25 @@
+---
+'@objectstack/service-storage': patch
+'@objectstack/plugin-sharing': patch
+'@objectstack/runtime': patch
+---
+
+hooks: drop the last three `doc` / `previousDoc` alias reads on a hook context — read the engine's own keys only
+
+Behaviour is unchanged: every one of these limbs guarded against a producer that
+has never existed, so none of them could be reached.
+
+- `service-storage` attachment lifecycle read `ctx.result ?? ctx.input.doc ?? ctx.input.data`
+- `plugin-sharing` primary-BU projection read `(ctx.input.data ?? ctx.input.doc).user_id`
+- `runtime`'s hook sandbox read `engineCtx.input ?? engineCtx.doc` and `engineCtx.previous ?? engineCtx.previousDoc`
+
+Every ObjectQL write context spells the payload `data` — measured and pinned by
+`hook-input-shape-contract.test.ts` in `@objectstack/objectql` ("insert carries
+`data` — never `doc`", #5273). The top-level pair is the same family one level
+up: `HookContextSchema` declares `input` / `result` / `previous` and neither a
+`doc` nor a `previousDoc`, and `engine.ts` — the sole producer of a HookContext
+— builds neither. The limbs survived only because the old `HookContext.input`
+contract table documented insert as `{ doc, options }`; that table was corrected
+in #5668, and the same alias was removed from `trigger-record-change` in #5671.
+These are the remainder (#5906), removed rather than left as a second de-facto
+contract (PD #12).