Merge branch 'main' into claude/issue-5126-strict-readonly-writes

Author: os-zhuang

.changeset/analytics-like-escape.md

@@ -0,0 +1,39 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): the three SQL compilers compare LIKE values literally (#5567)
+
+`$contains` / `$notContains` / `$startsWith` / `$endsWith` build a `LIKE` pattern
+around the comparand the author wrote. All three of this package's SQL compilers
+concatenated that comparand straight into a wildcard position — no escaping, no
+`ESCAPE` clause — so `_` (LIKE's single-character wildcard) and `%` (its
+multi-character one) stopped being literals. Measured on real SQLite, over the
+rows `x_admin` / `xyadmin` / `off 50% now` / `off 5012 now`:
+
+| `where`                          | returned      | correct |
+|----------------------------------|---------------|---------|
+| `{name: {$contains: '_admin'}}`  | `['1','2']`   | `['1']` |
+| `{name: {$contains: '50%'}}`     | `['3','4']`   | `['3']` |
+| `{name: {$startsWith: 'x_'}}`    | `['1','2']`   | `['1']` |
+| `{name: {$endsWith: '0% now'}}`  | `['3','4']`   | `['3']` |
+
+Every row is a **widening** — rows the author excluded came back — and
+`$notContains` is the mirror image, excluding rows the author kept. One of the
+three call sites is the ADR-0021 D-C read-scope (tenant + RLS) lowering, where a
+wider predicate is over-reach rather than a loose filter (the #5347 / #5324
+ruling on that same file). Prime Directive #3 forces machine names to
+`snake_case`, so essentially every machine-name comparand carries a `_` and hit
+this silently.
+
+All three compilers now escape the comparand and bind an explicit
+`ESCAPE` argument, matching what `driver-sql`'s `applyLike` has always done — so
+the same filter selects the same rows whichever strategy answers, and the
+`/analytics/sql` echo describes the statement that ran instead of a wider one.
+
+**No authoring change.** A comparand with no `_`, `%` or `\` binds exactly the
+pattern it bound before; only its meaning when it *does* carry one changes, from
+wildcard to literal. If you were relying on a comparand acting as a wildcard,
+that was never a declared capability of these operators — the spec describes them
+as substring / prefix / suffix matches — and `driver-sql` already read it
+literally, so the reading you got depended on which strategy served the query.

.changeset/calldata-record-not-found-unify.md

@@ -0,0 +1,51 @@
+---
+"@objectstack/runtime": patch
+"@objectstack/metadata-protocol": patch
+---
+
+fix(runtime): `callData`'s ObjectQL fallback answers a missing record id with 404 `RECORD_NOT_FOUND` (#5138)
+
+`callData` (the data bridge behind `/data`, the MCP bridge and the declarative
+endpoint executor) is protocol-first with an ObjectQL fallback. The fallback
+gave **three different answers to one fact** — that `id` names no row:
+
+| verb | before | on the wire |
+|---|---|---|
+| `get` | `return … : null` | `200 { data: null }` |
+| `update` | `throw new Error('[ObjectStack] Not Found')` — no `.status` | **500** |
+| `delete` | no existence check at all | `200 { deleted: true }` |
+
+The protocol path has answered `404 RECORD_NOT_FOUND` on all three verbs since
+#4435 (re-asserted for the batch path by #5088), so the answer to the same
+request depended on something no caller can see: whether the deployment
+registered the `protocol` slot (`MetadataPlugin` / `@objectstack/metadata-protocol`).
+All three fallback branches now throw the SAME envelope the protocol throws.
+
+Two of these were actively harmful. `update` reported a caller mistake as an
+internal fault — every dispatcher exit reads `.status` → `.statusCode` → 500, so
+a 4xx fact entered error reporting and alerting as a 5xx. `delete` reported
+success for a row that never existed, which is the hardest class to notice: an
+integrator reading `200` records the cleanup as done.
+
+The envelope is not re-spelled. `recordNotFoundError` is now exported from
+`@objectstack/metadata-protocol` and imported by the fallback, so there is one
+construction point and the two paths behind one `callData` cannot drift apart
+again.
+
+**Upgrade note.** If you run an assembly WITHOUT the metadata-protocol plugin
+(lean hosts, and the MCP multi-env path that threads a raw driver), these three
+calls change their answer for a missing id — from `200`/`200`/`500` to `404
+{ code: 'RECORD_NOT_FOUND', message: 'Record <id> not found in <object>' }`.
+Deployments that DO register the protocol slot are unaffected: they already
+answered `404` and this release does not touch that path. A client that
+branched on `data === null` from `GET /data/:object/:id` should branch on the
+`404` instead; a client that treated `DELETE` as idempotent should treat `404`
+as "already gone". Declarative endpoints (`object_operation`) inherit the same
+answer, since they reuse `/data`'s delegation.
+
+`delete`'s existence check is a `find` probe, not a read of what `ql.delete`
+returned: `IDataDriver.delete` declares `Promise< boolean >` and the protocol
+can read it, but `IDataEngine.delete` declares `Promise< any >` and the engine
+returns its driver's result through the hook chain — testing that for `false`
+would be reading a signal the contract does not promise, and it fails in the
+direction this fixes.

.changeset/embedded-host-unsealed-node-type-vocabulary-warns.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/service-automation': patch
+---
+
+自动化引擎:嵌入式 host 从未调用 `sealNodeTypeVocabulary()` 时,首次执行 flow 会告警一次(#4792)
+
+#4771 把 ADR-0018 的节点类型校验从 `registerFlow` 挪到了 `sealNodeTypeVocabulary()`。`AutomationServicePlugin` 在 `kernel:bootstrapped` 自动 seal,插件路径不受影响;但自己 `new AutomationEngine()` 且从不 seal 的嵌入式 host 就彻底拿不到这项校验,而且完全静默 —— 只有读过 changeset 的人才知道要补一行调用。现在这类 host 在第一次真正执行 flow 时会得到一条 `warn`,说明丢了什么、以及要调用哪个方法。
+
+- 首次执行是最早既安全又必然到达的时点:正在跑 flow 的 host 显然已经装配完毕(否则这次执行本身就会 `NO_EXECUTOR` 失败)。
+- **每个引擎实例一次**,不是每进程一次 —— 一个 host 建了多个引擎(按租户/环境各一个是常见形态)就是在每个上都漏了这次调用。
+- 告警只报「缺了这次调用」这个关于 host 的事实,**不报**未知节点类型的审计结果:未 seal 的引擎其词汇表按契约仍可增长,在那里断言「某类型没有执行器」正是 #4771 删掉的那种会被本次启动反驳的判断。需要审计结果又不想封闭词汇表的 host 用只读的 `getUnknownNodeTypeAudit()`。
+- 也**不会**顺带自动 seal:「谁决定词汇表封闭」只能有一个答案(host)。而且 seal 之后 `registerFlow` 会转为即时校验,自动 seal 会让「先执行、后注册插件执行器」(ADR-0018 允许)的嵌入式 host 开始收到 #4771 那种误报。
+
+走 `AutomationServicePlugin` 的部署与已显式调用过 `sealNodeTypeVocabulary()` 的 host 都不会多打任何日志(两条哨兵测试守着)。

.changeset/flow-bind-warning-structured-issues.md

@@ -0,0 +1,32 @@
+---
+"@objectstack/service-automation": patch
+---
+
+fix(service-automation): flow 绑定失败的告警改用结构化 `meta`,不再把 Zod issue 数组塞进单行日志 (#5048)
+
+`AutomationServicePlugin` 的五个 flow 绑定/读取失败点都把 `err.message` 插进一条
+单行 `logger.warn`。而 `registerFlow` 用 `FlowSchema` 解析,#4001 关闭 metadata
+schema 之后未知键是**抛出**而不是被丢弃 —— ZodError 的 `.message` 是 issue 数组的
+多行 JSON dump,第一行就是一个 `[`。
+
+两级管线随后把余下内容销毁:`ObjectLogger.write()` 每次调用只写一条
+`<ts> <LEVEL> <msg>` 记录,带换行的 message 会溢出到没有等级前缀的后续行;而
+`serve` 的启动诊断缓冲(`BootLogCapture.offer()`)只保留 `classifyBootLogLine`
+能认出等级前缀的行。于是一次启动里 24 个绑不上的 flow,给出的是 24 条点了名字、
+然后说一个 `[` 的告警 —— cloud#971 能横跨整条 rc.1 发布线没人发现,就是因为这个。
+
+现在这些位置改为:message 是不含换行的静态字符串,事实交给 logger 的 `meta`
+第二参(仓库里每个 `Logger` 实现都用 `JSON.stringify` 序列化它,值里的换行变成
+`\n` 转义,整条记录稳定占一行,正是启动缓冲会保留的形态)。新增内部模块
+`flow-bind-diagnostics.ts` 把 Zod issue 摊平成 `{ code, path, message,
+unrecognized }`:`path` 渲染成 `nodes[0].config.x`,被拒的键名放在
+`unrecognized` 而不是 Zod 原本的 `keys` —— 因为 `ObjectLogger` 的默认脱敏表
+(`['password','token','secret','key']`)按**子串**递归匹配,`keys` 含 `key`,
+原样转发 `err.issues` 会渲染成 `"keys":"***REDACTED***"`,恰好丢掉读者唯一需要
+的那个事实。issue 列表有上限,超出时用 `issueCount` **显式声明**总数,而不是静默
+截断。非 ZodError 的失败退回 `error` 字符串分支。
+
+无公开 API 变化;日志文本的可 grep 前缀(`cold-boot flow bind: failed to
+register`、`flow re-sync: failed to register`、`flow pull from ObjectQL
+registry failed`、`flow read from protocol failed`)全部保留。与 #4632 同源:
+被截断的诊断比没有诊断更贵。

.changeset/react-chart-aggregate-parse-gate.md

@@ -0,0 +1,64 @@
+---
+"@objectstack/lint": minor
+---
+
+feat(lint): the react-page publish gate PARSES `ChartAggregateSchema` instead of re-deriving it (#5020)
+
+`<ObjectChart aggregate={{…}}>` is judged at publish time by
+`validate-react-page-props`. That gate used to RE-DERIVE the aggregate's
+declaration: a local `CHART_FUNCTIONS` copy of the function vocabulary and a
+hand-written twin of the schema's count/field refinement. Two implementations of
+one contract, each free to drift — and, because unknown-key handling is a
+property of a **parse** rather than of a list of `if`s, a gate with no
+unknown-key check at all. The rule now calls `ChartAggregateSchema.safeParse()`
+on a statically resolvable literal, exactly as #5022 did for
+`ChartDrillDownSchema` beside it, and both hand-derived copies are deleted:
+`@objectstack/spec` is the single source of the vocabulary and the refinement
+again.
+
+**Newly reported (all `error`, all previously silent).** These are shapes the
+schema, the published react-blocks type and objectui's renderer already agreed
+were wrong; the old gate simply could not see them:
+
+| authored | before | after |
+|---|---|---|
+| `aggregate={{ field: 'total', groupBy: 'status' }}` (no `function`) | accepted | `aggregate.function: Invalid option: expected one of "count"\|"sum"\|"avg"\|"min"\|"max" (nothing is set there)` |
+| `aggregate={{ field: 42, function: 'sum', groupBy: 'status' }}` | accepted | `aggregate.field: Invalid input: expected string, received number` |
+| `aggregate={{ function: 'count', groupBy: 42 }}` | accepted | `aggregate.groupBy: Invalid input (received 42) — no accepted form matched: (1) … (2) …` |
+| `aggregate="count"` / `aggregate={[]}` | accepted | `aggregate must be a configuration object, not string.` |
+
+**Re-worded, same verdict.** Two messages now arrive from the schema rather than
+from this rule's own copy. If you match on lint output, update the text:
+
+- FROM `aggregate.function "median" is not an aggregation this chart can run.`
+  (hint: `Use one of: count, sum, avg, min, max.`)
+  TO `aggregate.function: Invalid option: expected one of "count"|"sum"|"avg"|"min"|"max" (received "median")`
+  — the vocabulary is the enum's own, and the author's value is echoed back from
+  the input (the one part zod does not put in the message).
+- FROM `aggregate.function "sum" has no "field" to aggregate.`
+  TO `aggregate.field: aggregate.function "sum" needs a "field" to aggregate (only "count" may omit it).`
+  — verbatim from the schema's refinement.
+
+The rule id (`react-chart-aggregate-invalid`) and the severity are unchanged for
+both.
+
+**`aggregate.groupBy` missing is a NEW `warning`, deliberately not an error.**
+It is the one violation the platform does not agree with itself about:
+`ChartAggregateSchema` and the published react-blocks type both declare `groupBy`
+**required**, while objectui's `ObjectChart` honours its absence
+(`schema.aggregate?.groupBy || schema.xAxisKey`) and this protocol's own
+`chartAggregateCategoryKey` documents the ungrouped single-row result. Gating it
+would break a working authoring shape to enforce a declaration the platform does
+not keep, so the finding explains the situation and does not fail
+`os lint`/`validate`/`compile`. Whether the schema loosens or the renderer
+tightens is decided on #5583.
+
+**What this does NOT fix yet.** `ChartAggregateSchema` and `ChartGroupBySchema`'s
+object arm are still STRIP-posture, so the parse this gate now runs **drops** an
+unknown key rather than reporting it: `groupby` for `groupBy` and
+`dateGranularty` for `dateGranularity` still degrade a chart to one ungrouped
+point with the build green. Wiring the parse is the precondition for closing
+that, not the closing — `.strict()` is a property of a parse, and until now there
+was no parse to make strict. The spec-side tightening is **#5583**; the tolerance
+is pinned by name in this rule's tests so a wired gate cannot be mistaken for a
+closed one (#4583).

.changeset/rest-unclassified-error-server-fault-status.md

@@ -0,0 +1,50 @@
+---
+"@objectstack/rest": patch
+---
+
+fix(rest): an unclassified route error answers a sanitised 500, not a 400 (#5489)
+
+**升级须知 — 状态码行为变化。** `@objectstack/rest` 的错误映射 `mapDataError`
+在所有分类分支都不匹配时,原先的终局兜底是
+`{ status: 400, body: { error: <原始 message> } }`。这一支现在改为一个消毒过的
+服务端故障信封:
+
+```
+500 {"error":"Internal server error","code":"INTERNAL_ERROR"}
+```
+
+**为什么。** 400 的语义是「你请求错了」——SDK、fetch 封装、代理和重试策略都据此
+判定「不要重试,调用方得改点什么」。而真正落到这一支的错误恰恰相反:元数据存储
+读不到时 `matchEndpoint` 按契约抛错(它抛就是为了让 outage 不伪装成「没有声明
+任何 endpoint」,ADR-0110 D3),或者干脆是处理器自身的 `TypeError`。两者调用方都
+修不了,且都**应该**重试。实测:`GET /api/v1/meta/api` 对着一个抛
+`Error('metadata store unreachable')` 的存储,返回 HTTP 400。
+
+同时,原始 message 是逐字下发的——而这偏偏是全文件里最没有证据表明可以下发的一
+条路径:走到这里的前提就是 `looksLikeInternalErrorLeak` 什么都没匹配上,而
+#5462 已经记过「关键词启发式沉默不等于安全」。实测到的一例:一个声明了
+`status: 502`、message 为 `connect ECONNREFUSED 10.0.0.5:5432 (internal pool)`
+的错误,经由数据路由直接调用 `mapDataError` 时,以 400 携带主机与端口下发。
+沿用 #5464 的纪律:原文进服务端日志,不进客户端(500 不在
+`isExpectedDataStatus` 内,`handleRouteError` 会打印完整错误对象)。
+
+**真正的客户端错误一个都没有改变。** 改动前先做了测绘:给这一支加桩,跑完
+`@objectstack/rest` 全套(48 文件 / 719 用例),落到这一支的只有 6 个错误——本单
+的存储 outage、两个 502 的 ECONNREFUSED、三个 `TypeError`,没有一个是客户端
+错误。历史上唯一骑在这条兜底上的客户端错误家族(driver-sql 无法编译的 filter
+拒绝)已由 #4436 在**生产者侧**声明 `status: 400` + `INVALID_FILTER` 迁走。
+validation / permission / unknown object / unknown field / not-null 漂移 /
+unique 冲突 / 沙箱业务拒绝等全部仍由各自分支给出原本的 4xx。
+
+**`INTERNAL_ERROR` 而非 `DATABASE_ERROR`。** #5462 的 `DATA_STORE_FAULT`
+(`500 DATABASE_ERROR`)用在证据**指名**了存储故障的地方(驱动的 missing-relation
+措辞、`looksLikeInternalErrorLeak` 命中);而这一支的定义性事实是「没有任何证据」,
+把处理器的 `TypeError` 报成 `DATABASE_ERROR` 会把运维指向一个其实健康的数据库。
+`INTERNAL_ERROR` 是 `standardErrorCodeForHttpStatus(500)` 的取值
+(`@objectstack/spec` 的 `HttpStatusErrorCodeMap`)——目录自己为「500 且无更具体
+code」定义的下限,不是第三套措辞;message 复用的也是
+`resolveErrorResponse` 声明式 5xx 分支已在用的 `INTERNAL_ERROR_MESSAGE`。
+
+**如果你的客户端把这条兜底当 400 处理过**:它现在是 5xx,可以重试;若你有生产者
+依赖「不声明 status 即可把 message 原文送达调用方」,请改为在抛出点声明
+`status` 与 `code`(契约优先),那是唯一仍会把措辞交给调用方的路径。

.changeset/storage-local-root-env-channel.md

@@ -0,0 +1,44 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): `OS_STORAGE_ROOT` now actually takes effect — renamed to `OS_STORAGE_LOCAL_ROOT`, the name the settings service reads (#4968)
+
+The CLI and the settings service spelled the local storage root differently.
+The CLI wrote its own invented name, `OS_STORAGE_ROOT`; the settings service
+derives the env name for the same value from the namespace it owns —
+`envKeyOf('storage', 'local_root')` = `OS_STORAGE_LOCAL_ROOT` — and nothing in
+the repo ever set that. So the two channels never met: `os serve` constructed a
+local adapter at the root the operator named, `StorageServicePlugin` re-resolved
+from settings at `kernel:ready`, found only the manifest's **schema default**,
+and swapped the adapter to `./.objectstack/data/uploads`.
+
+`OS_STORAGE_ROOT` therefore took effect for exactly one value — the one that
+happens to equal that default — which is why plain `pnpm dev` never showed it.
+Every other value was constructed and then discarded:
+
+- **Production**: `OS_STORAGE_ROOT=/srv/uploads` was ignored and uploads landed
+  under the process cwd. An operator following `backup-restore.mdx` backed up an
+  empty directory.
+- **`dev --fresh`**: the tempdir was documented to own all state for the run;
+  uploads actually went to the project cwd and survived process exit.
+- Every clean boot logged a data-loss-grade "adapter swapped … existing files
+  were NOT migrated" warning. That warning was **accurate** — the swap really
+  happened — and is untouched here. It stops firing because the swap stops.
+
+The fix is at the producer, not as a tolerant read in the consumer: `dev.ts`
+publishes `OS_STORAGE_LOCAL_ROOT`, and `serve.ts` resolves the root through one
+channel (`resolveStorageLocalRootEnv`), shared with `os migrate`'s storage
+bootstrap so the CLI materialises bytes exactly where the server would.
+
+`OS_STORAGE_ROOT` keeps working for **one release** via
+`readEnvWithDeprecation('OS_STORAGE_LOCAL_ROOT', 'OS_STORAGE_ROOT')`, warning
+once per process, and is then removed. When the legacy name supplies the value
+it is also stamped onto the canonical name, because the settings service only
+ever looks up `OS_STORAGE_LOCAL_ROOT` — without the stamp a deployment on the
+old spelling would keep the original defect in full.
+
+Storage settings now resolve `source: 'env'` at the value the adapter was built
+with, so Setup → Settings → File Storage shows the directory actually in use.
+No change to `packages/services/service-storage` — the swap predicate is correct
+and stays as is.