Merge branch 'main' into claude/issue-5515-sync-arch-l3-sap

Author: os-zhuang

.changeset/analytics-canonical-number-comparand.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): only a canonical numeric spelling is recovered as a number, so `'007'` / `'1.50'` stay strings (#5528)
+
+An analytics `where` round-trips every comparand through the internal
+`values: string[]` form — `stringifyForCube` on the way out, and
+`coerceFilterValueForSql` / `coerceFilterValueForObjectQL` on the way back. The
+decoder decided "this is a number" from the string's **shape** alone
+(`/^-?\d+(\.\d+)?$/`), which cannot distinguish a number that was stringified on
+the way out from a string the author actually wrote.
+
+Measured before the fix, on cube `orders` / TEXT column `code`:
+
+| author's `where` | leaf `values` | SQL bind | engine comparand |
+|---|---|---|---|
+| `{code: {$eq: '007'}}` | `["007"]` | `7` | `7` |
+| `{code: {$eq: '0912'}}` | `["0912"]` | `912` | `912` |
+| `{code: {$eq: '1.50'}}` | `["1.50"]` | `1.5` | `1.5` |
+
+Both consumers were affected: the raw-SQL bind in `NativeSQLStrategy` and the
+comparand handed to the ObjectQL aggregate engine.
+
+The failure was **silent and mis-targeted, not empty**. Against a text column
+SQLite applies the column's affinity to the integer bind, so a widget filtered on
+order number `'007'` returned the row storing `'7'` — a different row, with no
+error to read; on Postgres the same query is a `text = integer` type error, and on
+the engine path the strict comparison simply matched nothing (measured: 0 rows).
+Zero-padded and trailing-zero strings are ordinary business shapes — order
+numbers, work orders, SKUs, dialling codes, postcodes, `'1.50'` prices.
+
+Recovery is now limited to a number's **own canonical spelling**
+(`String(Number(s)) === s`):
+
+- a comparand that really was a number is `String(n)` by construction, so it
+  still round-trips — `7` → `'7'` → `7`, `1.5` → `'1.5'` → `1.5`, `-3` → `-3`;
+- a string `Number()` would rewrite — `'007'`, `'0912'`, `'1.50'`, `'1.0'`,
+  `'-0'`, or more digits than a double holds — cannot have come from a number, so
+  it stays the string the author wrote.
+
+The narrowing can only ever **remove** recoveries: the shape regex still runs
+first, so `'1e3'`, `'1e+21'`, `'+7'`, `' 7'`, `'0x10'`, `'Infinity'` and `'NaN'`
+were strings before this change and are strings after it. This also aligns with
+ADR-0053 D-A2, which demoted this textual type re-derivation to a last resort
+behind the driver-backed `coerceTemporalFilterValue` hook.
+
+**Stopgap, and named as one.** `values: string[]` still has no escape, so the
+author strings `'null'` / `'true'` / `'false'` still collide with the tokens the
+encoder writes for the real `null` and booleans. Making the round trip lossless —
+tagged values, or an `unknown[]` internal representation — is #5526; the
+collision is pinned as unchanged in
+`src/__tests__/filter-value-canonical-number.test.ts` so it is not mistaken for
+fixed.

.changeset/analytics-contains-canonical-operator.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): `contains` 以规范算子 `$contains` 送进引擎,比较值不再落进正则位置(#5557)
+
+`ObjectQLStrategy.convertFilter` 在同一个 `switch` 里处理 LIKE 家族的四个算子。
+其中三个(`notContains` / `startsWith` / `endsWith`)自 #4128 起就是规范 spec 算子,
+只有 `contains` 是 `{ $regex: values[0] }` —— 比较值**原样**放进一个正则位置,不转义。
+
+实测(修复前 → 修复后,引擎收到的 filter):
+
+| `where` | 修复前 | 修复后 |
+|---|---|---|
+| `{stage: {$contains: 'a.b'}}` | `{stage: {$regex: 'a.b'}}` | `{stage: {$contains: 'a.b'}}` |
+| `{stage: {$notContains: 'a.b'}}` | `{stage: {$notContains: 'a.b'}}` | 不变 |
+| `{stage: {$startsWith: 'a.b'}}` | `{stage: {$startsWith: 'a.b'}}` | 不变 |
+| `{stage: {$endsWith: 'a.b'}}` | `{stage: {$endsWith: 'a.b'}}` | 不变 |
+
+三条后果,都是作者没有要求过的行为,且都不依赖 #4706 对 `$regex` 语义的裁决:
+
+1. **`$regex` 不在契约里。** `filter.zod.ts` 的 `FILTER_OPERATORS` 声明 15 个算子,
+   没有 `$regex` —— 这是**生产方**在发送 schema 未声明的算子。按 Prime Directive #12
+   修生产方(一个 `case` 标签),而不是给消费方加宽容。
+2. **同一棵过滤树在同包两个消费方之间不通。** `read-scope-sql.ts` 的
+   `compileScopedFilterToSql` 也是一个 `FilterCondition` 消费方,`compileOperator`
+   的 `default` 是 fail-closed,于是它对本策略产出的 filter 直接抛
+   `unsupported operator "$regex" … (fail-closed)`。
+3. **行结果取决于哪个驱动来答。** 把 `$regex` 当真正则求值的后端(driver-memory 的
+   `memory-matcher.ts` 就是,而且是有意为之 —— 服务 plugin-auth 的 ObjectQL adapter)
+   把 `a.b` 读成「a、任意一个字符、b」,于是 `axb` 也被匹配上;而 `50% (+)` 作为正则
+   根本编译不过(`Nothing to repeat`),`catch` 之后 `return false` —— 一个**有匹配行**
+   的筛选器静默返回零行,作者那边只看到「无数据」。同一个 `$contains` widget 在
+   `driver-sql` 上则被编译成子串 LIKE:同一张 dashboard,不同驱动,不同行集。
+
+`filter-normalizer.ts` 的 `MONGO_TO_CUBE_OP` 只把 `$contains` 映到 `contains`,
+别无来源,所以这里回送 `$contains` 就是作者自己那个 key 的往返。
+
+**测试**(`objectql-contains-canonical-operator.test.ts`,新增):引擎 filter 的算子键
+逐个对 `filter.zod.ts` 的 `ALL_OPERATORS` 校验(取自 spec 而非手抄一份);行结果跑在一个
+复刻 `memory-matcher.ts` 各 arm 的求值面上 —— `a.b` 只命中字面行、`50% (+)` 命中它该
+命中的那一行且**恰好**只有那一行(修复前分别是多一行和空集);同一个 filter 再送进
+`compileScopedFilterToSql` 确认它现在编译得过。只断言 filter/SQL 字符串会漏掉「不转义」
+这一半,所以两半都断言。
+
+顺带删掉 #5558(PR for #5333)在 `objectql-echo-operator-coverage.test.ts` 的替身引擎里
+留下的那处 `$regex` → `$contains` 翻译:它存在的理由就是本单,现在没有了。那也是本修复
+最直接的反向证据 —— 把 `case 'contains'` 退回 `$regex`,该文件的 `$contains` 行会以
+上面第 2 条的 fail-closed 报错红掉。

.changeset/analytics-echo-startswith-endswith.md

@@ -0,0 +1,54 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(service-analytics): `/analytics/sql` 回显补上 `$startsWith` / `$endsWith` 谓词(#5333)
+
+`ObjectQLStrategy.generateSql` 是同一棵过滤树的**第三个**编译器 —— 输出给浏览器的
+展示 SQL。它的 `buildFilterClauseSql` 显式处理 `set`/`notSet`/`in`/`notIn`/
+`contains`/`notContains`,其余落到只有六个条目的 `SCALAR_SQL_OPS` 查表;
+`startsWith` / `endsWith` 两处都不在,于是走到 `return null`,而**这棵树的每个编译器
+都把 `null` 读成「本节点没有约束」**。结果:
+
+| `where` | 实际执行(`NativeSQLStrategy`) | 修复前的回显 | 修复后的回显 |
+|---|---|---|---|
+| `{stage: {$startsWith: 'w'}}` | `WHERE stage LIKE $1` / `['w%']` | **没有 WHERE**,`params` 为空 | `WHERE stage LIKE $1` / `['w%']` |
+| `{stage: {$endsWith: 'n'}}` | `WHERE stage LIKE $1` / `['%n']` | **没有 WHERE**,`params` 为空 | `WHERE stage LIKE $1` / `['%n']` |
+| `{stage: {$contains: 'w'}}` | `WHERE stage LIKE $1` | `WHERE stage LIKE $1`(本来就对) | 不变 |
+
+回显比实际执行的查询**更宽**。这个字符串存在的唯一理由就是复现执行 —— 文件自己在渲染
+块顶上写着 “a rendering that contradicts execution is worse than no rendering” ——
+所以一个带着「为什么这张图少了几行」来看回显的作者,拿到的是一条**没有该筛选条件**的
+语句:跑一遍返回更多行,于是结论是「筛选器没生效」,而实际执行是生效的。与
+#3601 / #3602 / #3650 同一类「回显与执行不一致」,只是这次是从**算子表**这一侧到达的。
+
+不涉及越权或错行:该字符串从不执行(`execute()` 的 echo 会丢弃 `params`),损害限于
+可调试性。
+
+**两处修改:**
+
+1. **LIKE 家族收进一张表。** 新增 `LIKE_SQL_OPS`,四个算子(`contains` /
+   `notContains` / `startsWith` / `endsWith`)的 SQL 拼写与 pattern 并排放在一起,
+   与 `NativeSQLStrategy.buildFilterClause` 的 `opMap` / `likePattern` 逐条对应 ——
+   回显描述的正是那个编译器产出的语句,两张表并列摆着,漂移才看得见。
+   `contains` / `notContains` 的产物一字未变。
+
+2. **「渲染不了就静默丢」的出口改为 THROW。** `return null` 在这里与「无约束」同形,
+   所以下一个新增算子会以同样的方式再丢一次。之所以**可以**抛错:上游算子词汇表是
+   **封闭**的 —— `filter-normalizer.ts` 的 `fieldLeaves` 是叶节点的唯一生产者,它对
+   `MONGO_TO_CUBE_OP` 之外的算子在建叶之前就以 `INVALID_FILTER` / 400 拒绝。因此任何
+   调用方写出的过滤器都到不了这个出口;真到了,只能意味着 normalizer 的表新增了这里
+   没有分支的算子,那是我们自己两张表漂移,而对此**唯一不能给的答案就是悄悄放宽作者的
+   查询**。与 `convertFilter` 的 `default:` 分支在 #4128 做出的是同一个选择;刻意**不**用
+   `invalidFilterError` 的 400 信封 —— 这不是调用方形状的错误。
+
+**该 throw 出口今天从公共入口不可达,这一点是测过的、也是刻意报告的**:把它改回
+`return null`(保留第 1 项修改)只会让它自己那一条断言变红,枚举断言和回显对照表
+全部保持绿色。它是一个漂移探针,不是行为修复 —— 行为修复是第 1 项。
+
+新增 `objectql-echo-operator-coverage.test.ts`:issue 那张对照表按**行结果**钉住
+(回显语句在同一份 fixture 上真的被执行,行 id 与查询实际返回的行 id 比对 —— 丢掉的
+谓词藏不住,它返回的正是筛选器排除掉的行),再按 `filter.zod.ts` 的
+`FILTER_OPERATORS` 枚举全部 15 个可编写算子,逐个断言回显渲染出谓词、且
+placeholder 与 `params` 对齐。只断言 SQL 字符串会放过下一个未映射的算子 —— #4128 里
+`$between` 就藏在 `$startsWith` 后面。

.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/approval-revise-window-service-owned.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/spec": minor
+"@objectstack/plugin-approvals": minor
+"@objectstack/lint": minor
+---
+
+fix(approvals): the ADR-0044 revise window is a service-owned node type, not a bare `wait` (#3823)
+
+#3801 gated `POST /api/v1/automation/:name/runs/:runId/resume` on the **node type**
+that produced the suspension: an `approval` pause declares
+`resumeAuthority: 'service'`, so it continues only through `ApprovalService`.
+ADR-0044's **revise window** was the same trust boundary in a shape that key
+could not see. Send-back parked the run on an ordinary `wait` node the flow
+author placed — correctly `resumeAuthority: 'any'`, because a signal wait is
+*meant* to be resumable by an external producer — and `ApprovalService.resubmit`
+was the only thing that checked anything about continuing it.
+
+Demonstrated (not reasoned) against the real engine: a raw `resume(runId)` with
+an **empty body**, from any caller, walked the `resubmit` back-edge into the
+approval node and opened round N+1 with **no submitter check and no `resubmit`
+audit row** (`['submit','revise']` — no third row, ever). Worse, when another
+request was already pending on the record — the exact case `resubmit` refuses
+with `DUPLICATE_REQUEST` *specifically to keep the run alive* — the raw resume
+went around that guard: the approval node's re-entry failed **after** the engine
+consumed the suspension, and the run was **permanently destroyed** with its
+round-N request stuck `returned` and no resubmit able to reach it.
+
+The revise pause is therefore its own node type:
+
+- **`approval_revise`** (`APPROVAL_REVISE_NODE_TYPE`), registered by
+  `@objectstack/plugin-approvals` alongside the `approval` node, declaring
+  `resumeAuthority: 'service'`. It stays a first-class box on the canvas, in the
+  run log and in the suspended-run store — only the *reuse* of `wait` was wrong.
+  It takes **no config**: the window ends on the submitter's explicit resubmit,
+  never on a signal or timer. The `resumeAuthority` gate itself is unchanged.
+- `sendBack` refuses a `revise` edge whose target is not an `approval_revise`
+  node, **before any mutation** (like the existing missing-`revise`-edge check),
+  so no run can be parked in a window something else can advance.
+- New gating lint `flow-approval-revise-target-not-service-owned`
+  (severity `error`, on `os build` / `os validate` / `os lint` and the runtime
+  metadata publish gate) rejects the old shape at authoring time.
+
+**Upgrading a flow authored against the original ADR-0044 D3.** One token:
+
+- **FROM:** `{ id: 'wait_revision', type: 'wait', waitEventConfig: { eventType: 'signal', … } }`
+- **TO:** `{ id: 'wait_revision', type: 'approval_revise' }` — drop
+  `waitEventConfig` / any `config`; the window has no event to wait on.
+
+Until you do, such a flow keeps registering and running and its approvals stay
+decidable (`approve` / `reject` / `recall` / `reassign` are untouched), but
+**send-back is refused** with a message naming the node and this fix, and
+re-publishing it reports the lint error. A run *already parked* in a legacy
+revise window keeps its recorded node type (a republish never re-types a live
+pause) and is drained by `resubmit` or `recall` as usual.
+
+ADR-0044's 2026-07-28 amendment records the reversal of its D3 and of its
+`Alternatives` rejection of a service-owned revise pause, with the evidence
+above; the implementation section there records what shipped, why the approval
+node does not re-suspend itself instead, and why no ADR-0087 conversion was
+added for the old shape.

.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.