Merge remote-tracking branch 'origin/main' into claude/issue-6536-retire-export-field-meta-constraints

Author: claude

.changeset/driver-sql-unique-violation-predicate.md

@@ -0,0 +1,49 @@
+---
+"@objectstack/driver-sql": patch
+---
+
+fix(driver-sql): judge unique violations with the shared predicate, so a Postgres index build over dirty data no longer takes the boot down (#6543)
+
+`syncDeclaredIndexes` has a branch whose whole job is to keep a database
+BOOTING when existing rows violate a NULL-safe unique it was asked to create
+(the #5030 defect made data): the constraint is logged at `error` as not
+enforced, and the ADR-0120 D4 drift pre-flight reports the exact conflicting
+rows. Taking the process down instead would brick the deployment.
+
+It decided whether it was looking at that case with a private inline regex over
+the stringified message — `unique constraint failed|duplicate entry|duplicate
+key value`, the fourth hand-written spelling of this question #6250
+inventoried. That read one of the two channels drivers use, and on the DDL path
+the missing channel is the whole answer for one shipped dialect:
+
+| dialect | `CREATE UNIQUE INDEX` over duplicate rows says | old regex |
+|:---|:---|:---|
+| SQLite   | `UNIQUE constraint failed: product.code`                | matched |
+| MySQL    | `ER_DUP_ENTRY: Duplicate entry 'DUP' for key 'uniq_…'`  | matched |
+| Postgres | `could not create unique index "uniq_…"`, SQLSTATE 23505 | **missed** |
+
+Postgres does not reuse its DML phrasing for an index build: `duplicate key
+value violates unique constraint` is what a conflicting INSERT says, while a
+conflicting index BUILD says `could not create unique index "…"` and puts the
+verdict on `error.code` (SQLSTATE `23505`) with the offending tuple on
+`error.detail`. None of the three message limbs appear in it — so on Postgres
+the branch never fired, and a database with legacy duplicates failed to start
+rather than booting with the constraint reported as unenforced.
+
+Both discriminators in this file now call `isUniqueViolationError` from
+`@objectstack/types`, passing the **error object** rather than a pre-stringified
+message, so `code`, `errno` and the `cause` chain are read alongside `message`:
+
+- the #5030 boot-survival branch above;
+- the negative limb of the MySQL functional-key-part fallback in
+  `createNullSafeUniqueIndex`, which used a bare `/duplicate/i` to avoid
+  degrading a conflict into a "this server rejects functional key parts"
+  verdict — a message-only exclusion that did not fire on the `errno`-only
+  shape mysql2 can hand back.
+
+`patch` rather than `minor`: no API changes, and the message spellings that
+were recognised before are a strict subset of what the predicate recognises, so
+nothing that was absorbed before is absorbed differently now. The site's own
+business logic — the `nullSafe.size > 0` guard that keeps this absorption
+scoped to the NULL-safe case, and the "already exists" race arm that runs ahead
+of it — is unchanged.

.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/meta-object-read-effective-schema.md

@@ -0,0 +1,67 @@
+---
+"@objectstack/metadata-core": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/objectql": patch
+---
+
+fix(metadata-protocol): a `/meta` object read serves the effective runtime schema, whichever layer answered (#6562)
+
+`GET /api/v1/meta/object/:name` answered a **different set of fields** depending
+on which link of its resolution chain produced the answer, for the same object:
+
+- **registry-backed** → the schema AFTER `applySystemFields`, so it carried the
+  injected system columns — `created_at`, `created_by`, `updated_at`,
+  `updated_by`, `organization_id`, `owner_id`, `owning_business_unit_id` — even
+  when the author declared none of them;
+- **overlay-backed** (a `sys_metadata` customization row, or a MetadataService
+  body) → the stored document VERBATIM, so every one of those columns was simply
+  absent.
+
+Whether an object carries an overlay is invisible to the caller, so the same
+request reported the platform's own columns or not, and nothing in the response
+said which had happened. `/meta` is the machine-readable contract clients and AI
+authors code against: an author reading an overlay-backed object saw no
+`created_at` / `owner_id` / `organization_id` and reasonably concluded the
+columns do not exist — while every one of them is real in the database,
+filterable, orderable, and enforced read-only on write.
+
+**Every `/meta` object read exit now serves the effective schema.** The
+single-item read, the list, the cached/ETag branch, both draft reads and the
+layered read's `effective` layer all report the injected columns, with the same
+`readonly` / `system` markers the engine enforces (`owner_id` stays
+`readonly: false` — ownership is transferable). This is the presence half of the
+seam #4513 closed the value half of.
+
+Three things deliberately did **not** change:
+
+- **`?layers=1`'s `overlay` layer stays byte-verbatim.** Injection happens at the
+  read exits only, so Studio's "what you customised" diff never shows a column
+  nobody wrote. Only `effective` is injected.
+- **A `GET` → `PUT` round-trip still persists a byte-identical body** (#4326).
+  The write path gained the strip counterpart: a field byte-identical to the
+  platform's own definition is removed again on save, so a served document handed
+  straight back stores exactly what it stored before — same checksum, same
+  history diff. A declared `owner_id` carrying the author's own label is *not*
+  the platform's definition and survives untouched.
+- **A declared system column stays the author's.** Injection only ever adds a
+  column nobody declared; it never rewrites one that was.
+
+Which columns an object carries is `resolveInjectedSystemColumns`
+(`@objectstack/spec/data`, #5378) — the same derivation `applySystemFields`
+consumes — so every opt-out (`systemFields: false`, `managedBy: 'better-auth'`,
+`systemFields.audit`/`.tenant`, `tenancy.enabled: false`, the per-tier
+`ownership` table, the `sys_*` namespace) is answered in one place and re-derived
+in none. **What** each column looks like moves to `@objectstack/metadata-core`
+(`AUDIT_FIELD_DEFS` and the three tenancy/ownership anchors, re-exported from
+`@objectstack/objectql` so the symbols still resolve there) — the same relocation,
+for the same dependency cycle, as the audit-governance table in #4513:
+`@objectstack/objectql` depends on `@objectstack/metadata-protocol`, so the read
+path could not import the definitions from the registry that provisions them.
+One table now feeds the injection pass and the read exits, so they cannot drift.
+
+One key is deliberately not carried onto a served document: `organization_id`'s
+`indexed`. It is not a `FieldSchema` key — removed in the 16.x line (#2377,
+ADR-0049) and rejected by name by the strict schema — and its only consumer is
+`driver-mongodb`'s schema builder, which reads the registered schema and never a
+served document. It stays at the injection site; that the registry-backed read
+answers `_diagnostics: { valid: false }` because of it is filed as #6810.

.changeset/olive-donkeys-tickle.md

@@ -0,0 +1,16 @@
+---
+'@objectstack/lint': minor
+---
+
+Add the startup open-vocabulary verdict rule — "not registered YET" and "no provider at all" are the same value, and a verdict recorded from it is never retracted (#4776).
+
+A boot fills its registries incrementally, so asking one "is X there?" while it is still filling is fine — the answer is simply not final yet. Turning that not-yet into a **verdict and recording the verdict** is the defect: the provider registers a moment later and nothing goes back to undo the record. One showcase cold start produced three instances of the shape in three unrelated subsystems (#4769, #4771, #4772).
+
+`findStartupRegistryVerdicts(source, { file })` is a pure decision procedure over plugin source (parsed, never executed, never type-checked). It reports two rule ids:
+
+- `startup-open-vocabulary-verdict` — inside `constructor` / `init` / `start`, a read of a capability vocabulary ADR-0018 keeps runtime-extensible whose conclusion is **recorded** (announced in a `warn`/`error` log, cached in an instance field or module binding, or persisted). All three parts, or it is not a finding — a read-only probe is legal and is not flagged.
+- `startup-verdict-assertive-wording` — emitted only at a site the first rule already flagged, when the diagnostic asserts a terminal outcome about a world that has not finished forming ("will fail at execution time", "you need Redis").
+
+Every finding's hint prescribes the three shapes the fixes took: resolve where the value is used (a `kernel:ready` hook or a lazy accessor — `createLazyCacheRateLimitStorage()`, #4772), seal the vocabulary then judge (`AutomationEngine.sealNodeTypeVocabulary()`, #4771), or order the verdict after the mutation it describes (#4769). All three cures are recognised by shape and pass.
+
+Severity is always `warning` — the rule reasons about a boot sequence it cannot execute, so it advises and never gates. The kernel SERVICE-registry half of the same family stays with `pnpm check:startup-registry-verdict`; the rule module states the measured division of labour between the two.