merge origin/main (a7b854f)

Author: claude

.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/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`(契约优先),那是唯一仍会把措辞交给调用方的路径。

packages/metadata-protocol/src/index.ts

@@ -1,6 +1,10 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 export { ObjectStackProtocolImplementation, ConcurrentUpdateError, normalizeViewMetadata, graftNormalizedOperators, stripReadDecorations } from './protocol.js';
+// [#5138] The 404 envelope every single-record path answers, exported so the
+// ObjectQL FALLBACK in `@objectstack/runtime`'s `callData` builds the SAME one
+// instead of minting a second not-found shape. See `recordNotFoundError`.
+export { recordNotFoundError } from './protocol.js';
 export { createMetadataProtocolPlugin, assembleMetadataProtocol } from './plugin.js';
 export type { MetadataProtocolPluginOptions } from './plugin.js';
 export type { UninstallCleanup, UninstallCleanupOutcome } from './protocol.js';

packages/metadata-protocol/src/protocol.ts

@@ -340,8 +340,19 @@ function resolveOverlaySchema(type: string, _item: unknown): z.ZodTypeAny | null
  * params, #4190 stopped dropping filters) — a write that touched zero rows
  * reporting 200 is that shape one level up, on the verb where it costs the
  * most.
+ *
+ * [#5138] EXPORTED, for the same "cannot disagree about it" reason one layer
+ * out. `@objectstack/runtime`'s `callData` is protocol-first with an ObjectQL
+ * FALLBACK, and the fallback had reinvented this fact three incompatible ways
+ * (`get` → `null`, `update` → a bare `Error` with no status ⇒ 500, `delete` →
+ * no check at all ⇒ `200 { deleted: true }` for a row that never existed). It
+ * now calls THIS function, so the two paths behind one `callData` answer a
+ * missing id identically — which is the only reason a caller may stop caring
+ * which of them served it. Re-spelling the envelope there would have been a
+ * second not-found envelope; `RECORD_NOT_FOUND` (#5088) is the one this repo
+ * has.
  */
-function recordNotFoundError(object: string, id: string | number): Error {
+export function recordNotFoundError(object: string, id: string | number): Error {
     const err = new Error(`Record ${id} not found in ${object}`) as Error & {
         code?: string;
         status?: number;

packages/plugins/driver-sql/src/sql-driver.ts

@@ -467,6 +467,12 @@ const SQLITE_TIME_EXPR_REFS = 8;
  * tail (attribution, issue numbers) may be cut. Keep the actionable part —
  * operator, field, path, what arrived, what the spec declares — at the FRONT.
  *
+ * [#5489] The "without a status it reached the client verbatim" half is now
+ * history: that terminal branch answers a sanitised 500 (`INTERNAL_ERROR`).
+ * Declaring `status` + `code` at the throw site is therefore the ONLY way a
+ * refusal's words reach the caller at all — which is the contract-first
+ * arrangement #4436 wanted, no longer relying on a fallback that leaked.
+ *
  * The `[sql-driver]` prefix these messages used to carry is GONE from the text:
  * it is driver-internal wording, and shipping it to clients is exactly what the
  * #3867 sanitiser exists to stop. The operator/field/vocabulary detail — the
@@ -6272,6 +6278,16 @@ export class SqlDriver implements IDataDriver {
    * character (MySQL/Postgres do, but the explicit clause is correct for all
    * three). `shape` positions the wildcard: `contains` → `%v%`, `starts` → `v%`,
    * `ends` → `%v`.
+   *
+   * **Second implementation, deliberately** (#5567):
+   * `packages/services/service-analytics/src/like-pattern.ts` carries the same
+   * transform — same escaped character class, same three shapes, same bound
+   * `ESCAPE` — because `service-analytics` depends on no driver and this is a
+   * private method taking a knex builder, so there is nothing for it to import.
+   * That file's header explains the choice; it is held to THIS expression, character
+   * for character, by `service-analytics`'s `like-metacharacter-escape.test.ts`.
+   * A third hand-copy is the thing to refuse: import from one of the two, or add
+   * a consumer to that test.
    */
   private applyLike(
     builder: any,

packages/rest/src/rest-4xx-message-truncation.test.ts

@@ -147,6 +147,17 @@ describe('mapDataError: short 4xx messages are byte-for-byte unchanged (#5423)',
             Object.assign(new Error('connect ECONNREFUSED 10.0.0.5:5432 '.repeat(20)), { status: 502 }),
         );
         expect(r.status).not.toBe(502);
+        // [#5489] `not.toBe(502)` was true of the OLD landing too, and that
+        // landing was `400` with every byte of the ECONNREFUSED text — host and
+        // port included — on the wire. The negative assertion could not tell
+        // the two apart, so what it actually lands on is pinned here: this
+        // declared 5xx now leaves `mapDataError` through the terminal
+        // `UNCLASSIFIED_FAULT`, sanitised and in the server band. (The declared
+        // 502 is still not preserved on this direct-call path — that is
+        // `resolveErrorResponse`'s branch, and out of #5489's scope.)
+        expect(r.status).toBe(500);
+        expect(r.body.code).toBe('INTERNAL_ERROR');
+        expect(String(r.body.error)).not.toContain('10.0.0.5');
     });
 });
 

packages/rest/src/rest-5xx-message-sanitization.test.ts

@@ -44,6 +44,11 @@
 //        -> 404 Object 'showcase_account' is not registered
 //   500 `Failed to delete customization overlay: connect ECONNREFUSED ...`
 //        -> 400 with the driver text STILL verbatim (terminal fallback)
+//           [#5489] that terminal fallback is now a sanitised 500, so this
+//           third row's LEAK is closed at the source. The other two rows are
+//           untouched — they are mis-classifications by the text heuristics,
+//           not by the fallback — and the reason this fix stays in the branch
+//           itself (keep the producer's declared status) is unchanged.
 //
 // So it re-labels a server fault as a client mistake, re-labels a capability
 // refusal as a missing object, and — for any 5xx whose wording matches no

packages/rest/src/rest-endpoint-surfaces-served-only.test.ts

@@ -265,13 +265,16 @@ describe('#5224 — GET /meta/api announces only what the matcher serves', () =>
     const { rest } = mountRest(ALL_ENUMERATED, outage);
 
     const res = await getMetaApi(rest);
-    // The pin is that the request FAILS rather than answering a set. The exact
-    // status is not this change's to decide: an unrecognised error reaching
-    // `handleRouteError` lands on `mapDataError`'s terminal fallback, which
-    // this route measured at 400 — a pre-existing classification shared by
-    // every error on the metadata routes, not a consequence of the narrowing.
-    // Asserting 5xx here would pin someone else's bug as if it were fixed.
-    expect(res.statusCode).toBeGreaterThanOrEqual(400);
+    // [#5489] Promoted from `>= 400` to the 5xx band. #5487 deliberately left
+    // it at `>= 400` because the terminal fallback in `mapDataError` measured
+    // 400 here, and asserting 5xx would have pinned someone else's bug as if it
+    // were fixed. #5489 fixed it: an outage the mapper cannot attribute to the
+    // request is a server fault, which is what an SDK must read to decide that
+    // retrying is the right move. The route's own pin — that it FAILS rather
+    // than confidently answering "this deployment declares no endpoints" — is
+    // unchanged and is the second assertion.
+    expect(res.statusCode).toBeGreaterThanOrEqual(500);
+    expect(res.body?.code).toBe('INTERNAL_ERROR');
     expect(res.body?.items ?? res.body).not.toEqual([SERVED]);
   }, 60_000);
 });

packages/rest/src/rest-expected-error-logging.test.ts

@@ -25,6 +25,13 @@
 //    OPPOSITE overreach, a predicate widened to "any 4xx is expected", which
 //    would silence the un-coded 400 that `mapDataError` degrades an
 //    unrecognised error (a handler `TypeError`) to.
+//
+// [#5489] That last sentence describes the world before the unrecognised-error
+// fallback became a sanitised 500. The handler-bug case below now asserts 500;
+// its adversary is no longer a widened 4xx predicate but any future attempt to
+// add 500 to `isExpectedDataStatus`. The invariant it guards — a real handler
+// bug is never silent — is the same one, and is now carried by the status band
+// rather than by the absence of a `code`.
 
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { RestServer } from './rest-server';
@@ -168,20 +175,28 @@ describe('metadata routes — genuine faults keep the loud log (#4886)', () => {
         expect(res.statusCode).toBe(500);
     });
 
-    it('an UNRECOGNISED error (handler bug) stays loud even though it maps to 400', async () => {
-        // This is the case a blanket "any 4xx is expected" predicate would
-        // wrongly silence: `mapDataError` degrades anything it recognises
-        // nothing about to an UN-CODED 400, and that is where a real handler
-        // bug lands. Silencing it would be the mirror-image of #4886.
+    it('an UNRECOGNISED error (handler bug) stays loud — and is a 500, not a 400 (#5489)', async () => {
+        // The loudness is what #4886 pinned, and it is unchanged. What moved is
+        // WHY it is structural: this case used to land on `mapDataError`'s
+        // un-coded 400 fallback, so the guard read "loud even though it maps to
+        // 400" and its adversary was a predicate widened to "any 4xx is
+        // expected". #5489 made that fallback a sanitised 500
+        // (`UNCLASSIFIED_FAULT`) because a handler bug is not the caller's
+        // fault and an SDK must not read "do not retry" off it. 500 is outside
+        // `isExpectedDataStatus` entirely, so the log line no longer depends on
+        // the predicate staying narrow in the 4xx band.
         const bug = new TypeError('Cannot read properties of undefined (reading \'name\')');
         const { rest } = setup({ getMetaItem: vi.fn().mockRejectedValue(bug) });
 
         const res = await callMetaItem(rest, { type: 'object', name: 'showcase_account' });
 
         expect(unhandledLogs()).toHaveLength(1);
         expect(unhandledLogs()[0][1]).toBe(bug);
-        expect(res.statusCode).toBe(400);
-        expect(res.body?.code).toBeUndefined();
+        expect(res.statusCode).toBe(500);
+        expect(res.body?.code).toBe('INTERNAL_ERROR');
+        // The bug's own words are the operator's, not the client's — and the
+        // log line above is where they went.
+        expect(JSON.stringify(res.body)).not.toContain('Cannot read properties');
     });
 });