Merge remote-tracking branch 'origin/main' into claude/issue-6621-revert-registry-refresh

Author: claude

.changeset/field-when-root-allowlist.md

@@ -0,0 +1,75 @@
+---
+"@objectstack/formula": patch
+"@objectstack/lint": patch
+---
+
+字段级 `*When` 的未绑定根检查:黑名单翻成白名单,并把因果句按槽位分档
+
+同一段诊断上的两条**正交**分档轴,一次设计通过 —— 分开做会把这段文案写两遍,
+且第二遍推翻第一遍。
+
+## 轴一:根集合从 3 项黑名单翻成 3 项白名单(#6713)
+
+字段级 `visibleWhen` / `readonlyWhen` / `requiredWhen` 实测只绑 `record`、
+`previous`、`parent` 三个根,三处独立证据一致:服务端
+`rule-validator.ts` 的两处绑定(`readonlyWhen` 绑
+`{ record, previous, extra: { parent } }`,`requiredWhen` 绑
+`{ record, previous, ...parentScope }`);客户端 `evalFieldPredicate` 绑
+`record` + `previous` + 调用方 `scope`,而 objectui 全部五个字段级调用点
+(`form.tsx` ×3、`WizardForm.tsx`、`GridField.tsx`)传的 `scope` 只可能是
+`undefined` 或 `{ parent }`;作者端 objectui 的
+`FIELD_RULE_ROOTS = ['record', 'previous', 'parent']`,注释明写 "nothing else"。
+
+而检查此前是一张**黑名单** —— #6584 一项、#6711 三项
+(`current_user` / `user` / `ctx`)。黑名单在这个面上结构性地追不上
+`SCOPE_ROOTS`:每新增一个根都要有人记得抄过来(`current_user` 自己就是 #6290
+加进去、#6584 才被发现的)。实测有 **21 个根**落在这条缝里,它们同样未绑定、
+同样 fault、而且同样**静默** —— 都在 `SCOPE_ROOTS` 里,所以裸引用检查也从不
+报它们。其中两个是高可信度的作者笔误而非理论成员:
+
+- `os.user.id` —— ADR-0068 D1 的**第四种**用户拼写(`buildScope` 把同一个
+  `EvalUser` 挂在 `current_user` / `user` / `ctx.user` / `os.user` 下),#6711
+  收了三种,`os` 这一支没收;
+- `data.status == 'x'` —— `data` 是**元数据表单**里同一个 `visibleWhen` 键的
+  **合法**根(`view.zod.ts`:"Root: `record` … in runtime forms, or `data` in
+  metadata forms"),两种表单同一个键名、不同的根。
+
+判定改为 `SCOPE_ROOTS` 成员减去白名单,列表直接从 `@objectstack/formula` 取,
+不在消费端重述 —— 因此 `SCOPE_ROOTS` 将来新增的成员自动被覆盖。
+
+处方随之**按根分档**:用户根(`current_user` / `user` / `ctx` / `os`)保留原有
+的选项级 `visibleWhen` 与权限集 FLS 两条用户向处方;`data` 给出元数据表单 vs
+运行期表单的解释;其余根给出通用的「改写成 `record` 谓词」。此前只有用户向处方,
+对写了 `data.type == 'select'` 的作者是答非所问。
+
+## 轴二:因果句按槽位分档(#6716)
+
+三个槽位此前共用一句「falls back to VISIBLE … showing for everyone」,而这句话
+只对其中一个精确。三格全部**实测**,每格量了两端:
+
+- **`visibleWhen` —— 仅客户端、fail-OPEN,原文案正确。** 服务端根本不评估字段级
+  `visibleWhen`(`ConditionalFieldDef` 无此成员,`fieldsNeedPrior` 只看
+  `requiredWhen || readonlyWhen ||` 选项可见性),唯一裁决来自渲染端,
+  `resolveFieldRuleState` 对可见性传 `fallback: true`。
+- **`readonlyWhen` —— 两端方向相反,服务端说了算,原文案是反的。** 服务端
+  `isReadonlyWhenLocked` 命中 `unknownVariableOf` 后返回 `true`(#4889 的
+  carve-out,其触发条件正是未绑定根这一类),`stripReadonlyWhenFields` 随即把该
+  字段从 payload 中删除;客户端 `resolveFieldRuleState` 传 `fallback: false`,
+  表单仍渲染为可编辑。按 ADR-0057 D10(server enforces, client is courtesy)以
+  服务端为准:作者改了字段、保存报成功、值静默不落库。原文案告诉作者「对所有人
+  可见」—— 失败方向与排障方向都相反。
+- **`requiredWhen` —— 两端都 fail-OPEN,且与可见性无关。** 服务端记日志后
+  `continue`(#4977 明确没有采用 #4889 的 carve-out),客户端 `fallback: false`,
+  两端都不强制,记录带着空字段保存成功。原文案在这里不只是不精确,而是说错了
+  字段的哪个属性。
+
+`conditionalRequired` 在 `FieldSchema` 里是 `retiredKey`(按名字拒绝),解析后的
+编译路径上该分支是惰性的,因此给它一条与槽位无关的通用句,而不是编造第四格测量。
+
+## `@objectstack/formula`
+
+`SCOPE_ROOTS` 改为公开导出。一个绑定**封闭**根集合的面,必须能说出它**不**绑定
+的那些根,而那个补集就是 `SCOPE_ROOTS` 减去该面自己的白名单;消费端手抄的列表
+追不上这张表。注意它不能用 `firstUndeclaredReference` 替代:严格环境同时声明了
+CEL 的**类型名**,`type(record.x) == string` 里的 `string` 会被判成「能解析的根」
+—— 实测按可解析性判定会误杀这条合法谓词(1 例),按 `SCOPE_ROOTS` 成员判定不会。

.changeset/lifecycle-rotation-dialect-caveat.md

@@ -0,0 +1,24 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): `lifecycle.storage` 的 rotation 文案补上方言限定 —— O(1) 整分片 DROP 仅在 SQLite 成立 (#6631)
+
+`lifecycle.storage` 块的三处文案把 SQLite 独有的机制写成了 rotation 策略的无条件属性:
+`maxAge` guidance 的 "Rotation does not reap by age — it ... DROPs the oldest shard
+whole"、`strategy` describe 的 "(O(1) reclaim)"、以及模块 TSDoc 的 "Rotator
+(time-shard + DROP oldest)"。实测权威:物理分片是 SQLite-only 的驱动能力
+(`driver-sql` 的 `supportsRotation` 只在 `isSqlite` 下为 true,`rotateShards`
+在其他方言直接拒绝),Postgres/MySQL 走 LifecycleService 的 `'rotation-fallback'`
+分支 —— 按 `created_at` 的年龄批量 reap,恰是旧文案宣称 rotation 不使用的机制。
+
+三处文案改为驱动注释早已写对的表述:保留窗口(`shards` × `unit`)在所有方言上
+一致 —— 声明的边界处处成立;回收机制不一致 —— SQLite 整分片 DROP(O(1) 回收),
+其他方言按年龄 reap 同一窗口。`maxAge` guidance 的路由建议(用 `shards`/`unit`
+设窗口,或改用 `retention`)原样保留。
+
+**纯文案修改,接受面零变化**:`LifecycleSchema` 接受/拒绝的输入集合与改动前
+逐字节相同;`superRefine`(含 `retention.onlyWhen` × rotation 的拒绝及其理由)
+未触碰。批 20 测试新增两条 pin:guidance 与 describe 必须同时点名两条腿
+(SQLite 的分片 DROP 与其他方言的按龄 reap),并各带反空洞守卫,防止整段文案
+消失时 pin 静默变绿。

.changeset/limit-zero-presence-sql-doors.md

@@ -0,0 +1,62 @@
+---
+'@objectstack/driver-sql': patch
+'@objectstack/driver-memory': patch
+'@objectstack/driver-mongodb': patch
+'@objectstack/driver-turso': patch
+'@objectstack/spec': minor
+---
+
+drivers: `limit: 0` returns no records, on every driver and every read door
+
+`limit: 0` was ruled in #6485 to mean **return no records**. Three of the five shipped
+drivers did not honour it, in three different ways — and the ones that disagreed
+returned **more** data than was requested, which on an ADR-0021 RLS read scope is
+over-reach rather than a loose filter. Reachable since #6578: the client now puts
+`top=0` on the wire, so the answer depended on which driver a deployment configured.
+
+**`driver-memory` — the slice was dropped.** `find()` sliced with `if (query.limit)`,
+truthiness, and `0` is falsy. Measured before the fix, three rows seeded:
+`{ limit: 0 }` returned **3 of 3**, and `{ limit: 0, offset: 1 }` returned 2 — the
+OFFSET applied and the LIMIT silently did not, which is why every paging suite stayed
+green over it. Two more sites of the same shape in `memory-analytics.ts` (the `$limit`
+pipeline stage and the SQL string builder) moved with it. Mingo honours `{ $limit: 0 }`
+as zero records (measured), so presence is sufficient there.
+
+**`driver-mongodb` — the value was forwarded faithfully, to a client that means
+something else by it.** `buildFindOptions` already tested presence, so `0` arrived
+exactly as written — but the MongoDB Node driver DEFINES `limit: 0` as *no limit*, so
+the answer was still the whole collection. Fixed with an explicit short-circuit that
+returns the empty result **before the client is consulted** (`[]` from `find`, `null`
+from `findOne`, which had the same hole). No round trip is made for a query whose
+answer is already known, and no future change in the upstream driver's reading of `0`
+can move this behaviour. Deliberately `=== 0`, not `<= 0`.
+
+**`driver-sql` — two doors disagreed with a third.** `findRows()`, the door `find()`
+goes through, has always compiled `limit` on presence. Two others compiled it on
+truthiness:
+
+- `findWithWindowFunctions()` — the live window-function read door (#4286). Returns
+  rows, so this was user-visible wrong data: `{ limit: 0 }` returned the whole table.
+- `analyzeQuery()` / `explain()` — returns a plan. It compiled `select * from "orders"`
+  where `find()` sent `... order by "id" asc limit ?`, so it explained a statement
+  other than the one that would run.
+
+`offset` moved with `limit` at both doors for internal consistency only. That half is
+**measured to change nothing**: knex elides a zero offset on better-sqlite3, Postgres
+and MySQL alike. It is pinned as the no-op it is rather than reported as a fix.
+
+**`driver-turso` remote transport — an `OFFSET` with no `LIMIT` was a syntax error.**
+Surfaced by the new conformance control that reads with a bare offset. SQLite's grammar
+is `LIMIT expr [OFFSET expr]`, and this compiler emitted the two clauses independently,
+so `find(obj, { offset: N })` with no `limit` produced `near "OFFSET": syntax error` —
+for **every** `N`, and only on the remote transport (the local half goes through knex,
+which synthesises the `LIMIT -1` no-limit sentinel). Remote now builds the same
+statement knex does.
+
+Result sets only ever get **narrower**. A caller who wants every row should omit
+`limit` rather than pass `0`.
+
+`@objectstack/spec` gains `PAGINATION_ZERO_LIMIT_CASES`, the shared conformance
+case-set pinning this — with controls, so "return nothing, always" cannot pass it. All
+**five** drivers answer it, with **no DEBT rows**: future drift goes red at
+`check:driver-conformance` rather than being discovered in production.

.changeset/sso-providers-nav-label.md

@@ -0,0 +1,36 @@
+---
+'@objectstack/platform-objects': patch
+---
+
+Translate the Setup app's `nav_sso_providers` navigation entry in all four
+locales.
+
+`@objectstack/plugin-auth` contributes an **SSO Providers** entry into Setup's
+Access Control group (`sys_sso_provider`, priority 250), but no locale bundle
+carried a label for it: measured on `origin/main` `ea1d9165d`, a grep for
+`nav_sso_providers` over `en` / `zh-CN` / `ja-JP` / `es-ES` returned **0 each**,
+against a control probe (`nav_positions`) that returned 1 each. A deployment
+with an external IdP wired therefore rendered `SSO Providers` in English inside
+an otherwise fully translated Setup menu.
+
+| locale | label |
+| --- | --- |
+| `en` | SSO Providers |
+| `zh-CN` | SSO 提供方 |
+| `ja-JP` | SSO プロバイダー |
+| `es-ES` | Proveedores SSO |
+
+Each one matches that locale's existing `sys_sso_provider.pluralLabel`, since
+the nav entry opens exactly that object's list view.
+
+**Why no gate caught it.** `pnpm check:app-nav-i18n` (#5750) boots the real
+composition and asserts every *merged* Setup nav id carries a label in every
+locale — and `plugin-auth` spreads its `navigationContributions` in only when
+`authManager.isSsoWired()` is true. In the composition that gate boots, this
+entry is never contributed, never merged, and so never judged; the gate's header
+already declared that bound. This id is consequently the one Setup entry no
+boot-time check can reach, so it is pinned by hand instead, next to the dead-key
+tombstone (#6660) it is the converse of: one list holds ids whose label must be
+**gone**, the other ids whose label must **stay**. Making the gate itself
+union-aware was considered and deliberately left unbuilt — a separate
+maintainer-facing call, not a prerequisite for labelling the ids it cannot see.

.github/workflows/check-links.yml

@@ -33,6 +33,19 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v7
 
+      # ADR cross-link gate (#6592). `docs/adr/` is deliberately NOT added to the
+      # lychee globs below -- see the ⛔ note there for why -- so the decision
+      # registry gets its own resolver, in the same advisory lane.
+      #
+      # Deliberately `node` and not `pnpm`: the script has zero dependencies, so
+      # this lane needs no setup-node / corepack / `pnpm install`, and the whole
+      # advisory job stays a checkout plus two checks. It is also why an author
+      # can run it locally in any container (`pnpm check:adr-links` when a
+      # workspace install exists, `node scripts/check-adr-links.mjs` when it does
+      # not) -- which lychee, installed by the action at CI time, cannot offer.
+      - name: Check ADR cross-links
+        run: node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs
+
       - name: Check links with lychee
         uses: lycheeverse/lychee-action@v2
         with:
@@ -55,6 +68,18 @@ jobs:
           # suffix that a site route omits. Without this pair the gate cannot go
           # green at all: 1286 root-relative links fail as "Cannot resolve
           # root-relative link ... provide a root dir".
+          #
+          # ⛔ Do NOT add `docs/adr/**/*.md` here. It looks like the one-line fix
+          # for #6592 and it is not: measured on the pinned lychee 0.24.2, that
+          # glob reports 8 broken links today, every one a pre-existing ADR →
+          # source-tree link whose target moved out of this repo. This job would
+          # be red on every PR from the moment it merged, which is how an
+          # advisory lane becomes a lane nobody reads (#6028 landed it
+          # advisory-first specifically to earn a green streak). `docs/adr/` is
+          # checked by the `Check ADR cross-links` step above instead, which can
+          # freeze those 8 on a shrink-only baseline and fail on a NEW one --
+          # something neither `exclude` nor `.lycheeignore` can express, because
+          # neither ever tells you an entry stopped being needed.
           args: >-
             --offline
             --root-dir ${{ github.workspace }}/content

content/docs/kernel/runtime-services/data-service.mdx

@@ -1,6 +1,6 @@
 ---
 title: services.data
-description: CRUD runtime helper API for records (`get`, `find`, `create`, `update`, `delete`).
+description: CRUD runtime helper API for records (`query`, `get`, `find`, `create`, `update`, `delete`).
 ---
 
 # `services.data`
@@ -32,13 +32,38 @@ the code that **holds** the binding calls it, with plain arguments and no `ctx`
 ## Methods
 
 ```ts
-services.data.get<T = any>(object: string, id: string): Promise<GetDataResult<T>>
+services.data.query<T = any>(object: string, query: Partial<QueryAST>): Promise<PaginatedResult<T>>
 services.data.find<T = any>(object: string, options?: QueryOptions | QueryOptionsV2): Promise<PaginatedResult<T>>
+services.data.get<T = any>(object: string, id: string): Promise<GetDataResult<T>>
 services.data.create<T = any>(object: string, data: Partial<T>): Promise<CreateDataResult<T>>
 services.data.update<T = any>(object: string, id: string, data: Partial<T>): Promise<UpdateDataResult<T>>
 services.data.delete(object: string, id: string): Promise<DeleteDataResult>
 ```
 
+### Two list entries, one preference
+
+`query` and `find` both answer a list read with the same
+`{ records, total?, hasMore? }` envelope, and the Canonical source declares which
+of the two to prefer — the block above lists them in its declaration order.
+`data.query` is *"Advanced Query using ObjectStack Query Protocol"*; `data.find`
+carries an `@deprecated` tag in the same file: *"Use `data.query()` with standard
+QueryAST parameters instead. This method uses legacy parameter names."* The tag
+ships in the package's published type declarations, so an editor strikes `find`
+through at every call site and points at `query`. As with the options vocabulary
+below, the posture is the SDK's own, not this page's — it is recorded product
+direction ([#986](https://github.com/objectstack-ai/objectstack/issues/986):
+deprecate the legacy-parameter query entries, promote `data.query(AST)`).
+
+Deprecated means "prefer `query`", not "scheduled for removal in this version":
+`find` remains fully functional, keeps both of its option vocabularies (see
+[below](#find-options-canonical-and-legacy)), and the Canonical source still
+names `QueryOptionsV2` *"the recommended interface for `data.find()` queries"*
+for callers that stay on it. The capability line between the two entries is
+real, though. `find` rides GET query parameters, so it has no spelling for a
+`search` term or for nested `expand` detail — it refuses a nested expand with an
+error whose own text says to use `data.query()`. `query` POSTs the full
+`QueryAST` as a JSON body (`POST /data/:object/query`) and carries all of it.
+
 ## Canonical source
 
 Every sibling page in this chapter names a contract interface
@@ -60,6 +85,12 @@ key for key. A managed runtime binds `services.data` to this same shape.
 - `object`: short object name (for example `task`, `account`)
 - `id`: record ID for single-record operations
 - `data`: partial payload for create/update
+- `query` (`query`): a `Partial<QueryAST>` — the spec's query protocol shape
+  (`packages/spec/src/data/query.zod.ts`): `where` / `fields` / `orderBy` /
+  `limit` / `offset`, plus the AST-only clauses (`search`, `expand` with nested
+  detail, `aggregations`, `groupBy`, `having`). The AST's own `object` key is
+  not needed here: the server takes the target from the `object` argument (the
+  URL path) and overwrites anything the body says
 - `options` (`find`): filtering, sorting and pagination — two vocabularies, one
   behaviour; see the table below
 
@@ -97,7 +128,8 @@ silently rather than refused, so migrate an options object as a whole.
 ## Returns
 
 - `get`: single record payload
-- `find`: list payload + pagination metadata
+- `query`/`find`: list payload + pagination metadata — the same
+  `PaginatedResult` envelope for both
 - `create`/`update`: mutated record payload
 - `delete`: `{ object, id, success }` — the spec's `DeleteDataResponse`. The
   flag is `success`, not `deleted` (#5638)
@@ -133,7 +165,18 @@ export async function recentOrdersForContact(data: DataService, contactId: strin
     limit: 20,
   });
 
-  return { contact, orders };
+  // `query` — the Canonical source's preferred list entry — POSTs the same
+  // words as a Partial<QueryAST> body, and carries the clauses `find` has no
+  // GET spelling for. Here: per-relation `expand` detail, which `find`
+  // refuses with an error that itself points at `query`.
+  const { records: withContact } = await data.query<{ id: string; amount: number }>('sales_order', {
+    where: { contact_id: contact.id },
+    orderBy: [{ field: 'created_at', order: 'desc' }],
+    limit: 20,
+    expand: { contact_id: { object: 'contact', fields: ['name'] } },
+  });
+
+  return { contact, orders, withContact };
 }
 ```
 

package.json

@@ -42,6 +42,7 @@
     "check:skill-frame-freshness": "node scripts/check-skill-frame-freshness.mjs --self-test && node scripts/check-skill-frame-freshness.mjs",
     "check:skill-compatibility": "node scripts/check-skill-compatibility-version.mjs --self-test && node scripts/check-skill-compatibility-version.mjs",
     "check:adr-anchors": "node scripts/check-adr-anchors.mjs --self-test && node scripts/check-adr-anchors.mjs",
+    "check:adr-links": "node scripts/check-adr-links.mjs --self-test && node scripts/check-adr-links.mjs",
     "check:platform-checklist": "node scripts/checklist-select.mjs --self-test && node scripts/check-platform-checklist.mjs",
     "check:org-identifier": "node scripts/check-org-identifier.mjs",
     "check:authz-resolver": "node scripts/check-single-authz-resolver.mjs --self-test && node scripts/check-single-authz-resolver.mjs",